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 ) {} );