jQuery UI API – 部件库（Widget Factory）

代码实例：

初始化带有指定 disabled 选项的小部件：

$( ".selector" ).widget({ disabled: true });
    

在初始化后，获取或设置 disabled 选项：

// getter
var disabled = $( ".selector" ).widget( "option", "disabled" );
 
// setter
$( ".selector" ).widget( "option", "disabled", true );
    

支持多个类型：

• Boolean：当设置为 false 时，则不使用动画，元素会立即隐藏。当设置为 true 时，元素会使用默认的持续时间和默认的 easing 淡出。
• Number：元素将使用指定的持续时间和默认的 easing 淡出。
• String：元素将使用指定的特效隐藏。该值可以是一个内建的 jQuery 动画方法名称，比如 "slideUp"，也可以是一个 jQuery UI 特效 的名称，比如"fold"。以上两种情况的特效将使用默认的持续时间和默认的 easing。
• Object：如果值是一个对象，则 effect、delay、duration 和 easing 属性会被提供。如果 effect 属性包含 jQuery 方法的名称，则使用该方法，否则，它被认为是一个 jQuery UI 特效的名称。当使用一个支持额外设置的 jQuery UI 特效时，您可以在对象中包含这些设置，且它们会被传递给特效。如果 duration 或 easing 被省略，则使用默认值。如果 effect 被省略，则使用 "fadeOut"。如果 delay 被省略，则不使用延迟。

代码实例：

初始化带有指定 hide 选项的小部件：

$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
    

在初始化后，获取或设置 hide 选项：

// getter
var hide = $( ".selector" ).widget( "option", "hide" );
 
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
    

支持多个类型：

• Boolean：当设置为 false 时，则不使用动画，元素会立即显示。当设置为 true 时，元素会使用默认的持续时间和默认的 easing 淡入。
• Number：元素将使用指定的持续时间和默认的 easing 淡入。
• String：元素将使用指定的特效显示。该值可以是一个内建的 jQuery 动画方法名称，比如 "slideDown"，也可以是一个 jQuery UI 特效 的名称，比如"fold"。以上两种情况的特效将使用默认的持续时间和默认的 easing。
• Object：如果值是一个对象，则 effect、delay、duration 和 easing 属性会被提供。如果 effect 属性包含 jQuery 方法的名称，则使用该方法，否则，它被认为是一个 jQuery UI 特效的名称。当使用一个支持额外设置的 jQuery UI 特效时，您可以在对象中包含这些设置，且它们会被传递给特效。如果 duration 或 easing 被省略，则使用默认值。如果 effect 被省略，则使用 "fadeIn"。如果 delay 被省略，则不使用延迟。

代码实例：

初始化带有指定 show 选项的小部件：

$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
    

在初始化后，获取或设置 show 选项：

// getter
var show = $( ".selector" ).widget( "option", "show" );
 
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
    

• 该方法不接受任何参数。

代码实例：

基于一个选项设置小部件元素的背景颜色。

_create: function() {
  this.element.css( "background-color", this.options.color );
}
    

• fn
  类型：Function() 或 String
  描述：要调用的函数。也可以是小部件上方法的名称。
• delay
  类型：Number
  描述：调用函数前等待的毫秒数，默认为 0。

代码实例：

100 毫秒后在小部件上调用 _foo() 方法。

this._delay( this._foo, 100 );
    

• 该方法不接受任何参数。

代码实例：

当小部件被销毁时，从小部件的元素移除一个 class。

_destroy: function() {
  this.element.removeClass( "my-widget" );
}
    

• element
  类型：jQuery
  描述：要应用 focusable 行为的元素。

代码实例：

向小部件内的一组元素应用 focusable 样式：

this._focusable( this.element.find( ".my-items" ) );
    

• 该方法不接受任何参数。

代码实例：

向 create 事件处理程序传递小部件的选项，作为参数。

_getCreateEventData: function() {
  return this.options;
}
    

• 该方法不接受任何参数。

代码实例：

让小部件元素的 id 属性作为选项可用。

_getCreateOptions: function() {
  return { id: this.element.attr( "id" ) };
}
    

• element
  类型：jQuery
  描述：要隐藏的元素。
• option
  类型：Object
  描述：定义如何隐藏元素的设置。
• callback
  类型：Function()
  描述：元素完全隐藏后要调用的回调。

代码实例：

为自定义动画传递 hide 选项。

this._hide( this.element, this.options.hide, function() {
 
  // Remove the element from the DOM when it's fully hidden.
  $( this ).remove();
});
    

• element
  类型：jQuery
  描述：要应用 hoverable 行为的元素。

代码实例：

当悬浮在元素上时，向元素内所有的 div 应用 hoverable 样式。

this._hoverable( this.element.find( "div" ) );
    

注释：如果存在不带参数成功调用小部件时要执行的逻辑动作，初始化只能在这时处理。

• 该方法不接受任何参数。

代码实例：

如果设置了 autoOpen 选项，则调用 open() 方法。

_init: function() {
  if ( this.options.autoOpen ) {
    this.open();
  }
}
    

• element
  类型：jQuery
  描述：要取消绑定事件处理程序的元素。不像 _on() 方法，_off() 方法中元素是必需的。
• eventName
  类型：String
  描述：一个或多个空格分隔的事件类型。

代码实例：

从小部件的元素上取消绑定所有 click 事件。

this._off( this.element, "click" );
    

• 保持处理程序内适当的 this 上下文。
• 自动处理禁用的部件：如果小部件被禁用或事件发生在带有 ui-state-disabled class 的元素上，则不调用事件处理程序。可以被 suppressDisabledCheck 参数重写。
• 事件处理程序会自动添加命名空间，在销毁时会自自动清理。
• suppressDisabledCheck（默认值：false）
  类型：Boolean
  描述：是否要绕过禁用的检查。
• element
  类型：jQuery
  描述：要绑定事件处理程序的元素。如果未提供元素，this.element 用于未授权的事件，widget 元素 用于授权的事件。
• handlers
  类型：Object
  描述：一个 map，其中字符串键代表事件类型，可选的选择器用于授权，值代表事件调用的处理函数。

代码实例：

放置小部件元素内所有被点击的链接的默认行为。

this._on( this.element, {
  "click a": function( event ) {
    event.preventDefault();
  }
});
    

• key
  类型：String
  描述：要设置的选项名称。
• value
  类型：Object
  描述：为选项设置的值。

代码实例：

当小部件的 height 或 width 选项改变时，更新小部件的元素。

_setOption: function( key, value ) {
  if ( key === "width" ) {
    this.element.width( value );
  }
  if ( key === "height" ) {
    this.element.height( value );
  }
  this._super( key, value );
}
    

• options
  类型：Object
  描述：为选项设置的值。

代码实例：

如果小部件的 height 或 width 选项改变，调用 resize 方法。

_setOptions: function( options ) {
  var that = this,
    resize = false;
 
  $.each( options, function( key, value ) {
    that._setOption( key, value );
    if ( key === "height" || key === "width" ) {
      resize = true;
    }
  });
 
  if ( resize ) {
    this.resize();
  }
}
    

• element
  类型：jQuery
  描述：要显示的元素。
• option
  类型：Object
  描述：定义如何显示元素的设置。
• callback
  类型：Function()
  描述：元素完全显示后要调用的回调。

代码实例：

为自定义动画传递 show 选项。

this._show( this.element, this.options.show, function() {
 
  // Focus the element when it's fully visible.
  this.focus();
}
    

• arg
  类型：Object
  描述：要传递给父部件的方法的零到多个参数。

代码实例：

处理 title 选项更新，并调用付部件的 _setOption() 来更新选项的内部存储。

_setOption: function( key, value ) {
  if ( key === "title" ) {
    this.element.find( "h3" ).text( value );
  }
  this._super( key, value );
}
    

• arguments
  类型：Array
  描述：要传递给父部件的方法的参数数组。

代码实例：

处理 title 选项更新，并调用付部件的 _setOption() 来更新选项的内部存储。

_setOption: function( key, value ) {
  if ( key === "title" ) {
    this.element.find( "h3" ).text( value );
  }
  this._superApply( arguments );
}
    

事件名称是小部件名称和类型的小写字母串。

注释：当提供数据时，您必须提供所有三个参数。如果没有传递事件，则传递 null。

如果默认行为是阻止的，则返回 false，否则返回 true。当处理程序返回 false 时或调用 event.preventDefault() 时，则阻止默认行为发生。

• type
  类型：String
  描述：type 应该匹配回调选项的名称。完整的事件类型会自动生成。
• event
  类型：Event
  描述：导致该事件发生的原始事件，想听众提供上下文时很有用。
• data
  类型：Object
  描述：一个与事件相关的数据哈希。

代码实例：

当按下一个键时，触发 search 事件。

this._on( this.element, {
  keydown: function( event ) {
 
    // Pass the original event so that the custom search event has
    // useful information, such as keyCode
    this._trigger( "search", event, {
 
      // Pass additional information unique to this event
      value: this.element.val()
    });
  }
});
    

• 该方法不接受任何参数。

代码实例：

当点击小部件的任意锚点时销毁小部件。

this._on( this.element, {
  "click a": function( event ) {
    event.preventDefault();
    this.destroy();
  }
});
    

• 该方法不接受任何参数。

代码实例：

当点击小部件的任意锚点时禁用小部件。

this._on( this.element, {
  "click a": function( event ) {
    event.preventDefault();
    this.disable();
  }
});
    

• 该方法不接受任何参数。

代码实例：

当点击小部件的任意锚点时启用小部件。

this._on( this.element, {
  "click a": function( event ) {
    event.preventDefault();
    this.enable();
  }
});
    

• optionName
  类型：String
  描述：要获取的选项的名称。

代码实例：

获得 width 选项的值。

this.option( "width" );
    

• 该方法不接受任何参数。

代码实例：

记录每个小部件选项的键/值对，用于调试。

var options = this.option();
for ( var key in options ) {
  console.log( key, options[ key ] );
}
    

• optionName
  类型：String
  描述：要设置的选项的名称。
• value
  类型：Object
  描述：要为选项设置的值。

代码实例：

设置 width 选项为 500。

this.option( "width", 500 );
    

• options
  类型：Object
  描述：要设置的 option-value 对。

代码实例：

设置 height 和 width 选项为 500。

this.option({
  width: 500,
  height: 500
});
    

• 该方法不接受任何参数。

代码实例：

当创建小部件时，在小部件的原始元素周围放置一个红色的边框。

_create: function() {
  this.widget().css( "border", "2px solid red" );
}
    

• event
  类型：Event
• ui
  类型：Object

注意：ui 对象是空的，这里包含它是为了与其他事件保持一致性。

代码实例：

初始化带有指定 create 回调的小部件：

$( ".selector" ).widget({
  create: function( event, ui ) {}
});
    

绑定一个事件监听器到 widgetcreate 事件：

$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );