jQuery UI API – 部件庫(kù)（Widget Factory）

代碼實(shí)例：

初始化帶有指定 disabled 選項(xiàng)的小部件：

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

在初始化后，獲取或設(shè)置 disabled 選項(xiàng)：

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

支持多個(gè)類(lèi)型：

• Boolean：當(dāng)設(shè)置為 false 時(shí)，則不使用動(dòng)畫(huà)，元素會(huì)立即隱藏。當(dāng)設(shè)置為 true 時(shí)，元素會(huì)使用默認(rèn)的持續(xù)時(shí)間和默認(rèn)的 easing 淡出。
• Number：元素將使用指定的持續(xù)時(shí)間和默認(rèn)的 easing 淡出。
• String：元素將使用指定的特效隱藏。該值可以是一個(gè)內(nèi)建的 jQuery 動(dòng)畫(huà)方法名稱，比如 "slideUp"，也可以是一個(gè) jQuery UI 特效 的名稱，比如"fold"。以上兩種情況的特效將使用默認(rèn)的持續(xù)時(shí)間和默認(rèn)的 easing。
• Object：如果值是一個(gè)對(duì)象，則 effect、delay、duration 和 easing 屬性會(huì)被提供。如果 effect 屬性包含 jQuery 方法的名稱，則使用該方法，否則，它被認(rèn)為是一個(gè) jQuery UI 特效的名稱。當(dāng)使用一個(gè)支持額外設(shè)置的 jQuery UI 特效時(shí)，您可以在對(duì)象中包含這些設(shè)置，且它們會(huì)被傳遞給特效。如果 duration 或 easing 被省略，則使用默認(rèn)值。如果 effect 被省略，則使用 "fadeOut"。如果 delay 被省略，則不使用延遲。

代碼實(shí)例：

初始化帶有指定 hide 選項(xiàng)的小部件：

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

在初始化后，獲取或設(shè)置 hide 選項(xiàng)：

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

支持多個(gè)類(lèi)型：

• Boolean：當(dāng)設(shè)置為 false 時(shí)，則不使用動(dòng)畫(huà)，元素會(huì)立即顯示。當(dāng)設(shè)置為 true 時(shí)，元素會(huì)使用默認(rèn)的持續(xù)時(shí)間和默認(rèn)的 easing 淡入。
• Number：元素將使用指定的持續(xù)時(shí)間和默認(rèn)的 easing 淡入。
• String：元素將使用指定的特效顯示。該值可以是一個(gè)內(nèi)建的 jQuery 動(dòng)畫(huà)方法名稱，比如 "slideDown"，也可以是一個(gè) jQuery UI 特效 的名稱，比如"fold"。以上兩種情況的特效將使用默認(rèn)的持續(xù)時(shí)間和默認(rèn)的 easing。
• Object：如果值是一個(gè)對(duì)象，則 effect、delay、duration 和 easing 屬性會(huì)被提供。如果 effect 屬性包含 jQuery 方法的名稱，則使用該方法，否則，它被認(rèn)為是一個(gè) jQuery UI 特效的名稱。當(dāng)使用一個(gè)支持額外設(shè)置的 jQuery UI 特效時(shí)，您可以在對(duì)象中包含這些設(shè)置，且它們會(huì)被傳遞給特效。如果 duration 或 easing 被省略，則使用默認(rèn)值。如果 effect 被省略，則使用 "fadeIn"。如果 delay 被省略，則不使用延遲。

代碼實(shí)例：

初始化帶有指定 show 選項(xiàng)的小部件：

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

在初始化后，獲取或設(shè)置 show 選項(xiàng)：

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

基于一個(gè)選項(xiàng)設(shè)置小部件元素的背景顏色。

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

• fn
  類(lèi)型：Function() 或 String
  描述：要調(diào)用的函數(shù)。也可以是小部件上方法的名稱。
• delay
  類(lèi)型：Number
  描述：調(diào)用函數(shù)前等待的毫秒數(shù)，默認(rèn)為 0。

代碼實(shí)例：

100 毫秒后在小部件上調(diào)用 _foo() 方法。

this._delay( this._foo, 100 );
	

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

當(dāng)小部件被銷(xiāo)毀時(shí)，從小部件的元素移除一個(gè) class。

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

• element
  類(lèi)型：jQuery
  描述：要應(yīng)用 focusable 行為的元素。

代碼實(shí)例：

向小部件內(nèi)的一組元素應(yīng)用 focusable 樣式：

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

向 create 事件處理程序傳遞小部件的選項(xiàng)，作為參數(shù)。

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

讓小部件元素的 id 屬性作為選項(xiàng)可用。

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

• element
  類(lèi)型：jQuery
  描述：要隱藏的元素。
• option
  類(lèi)型：Object
  描述：定義如何隱藏元素的設(shè)置。
• callback
  類(lèi)型：Function()
  描述：元素完全隱藏后要調(diào)用的回調(diào)。

代碼實(shí)例：

為自定義動(dòng)畫(huà)傳遞 hide 選項(xiàng)。

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

• element
  類(lèi)型：jQuery
  描述：要應(yīng)用 hoverable 行為的元素。

代碼實(shí)例：

當(dāng)懸浮在元素上時(shí)，向元素內(nèi)所有的 div 應(yīng)用 hoverable 樣式。

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

注釋：如果存在不帶參數(shù)成功調(diào)用小部件時(shí)要執(zhí)行的邏輯動(dòng)作，初始化只能在這時(shí)處理。

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

如果設(shè)置了 autoOpen 選項(xiàng)，則調(diào)用 open() 方法。

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

• element
  類(lèi)型：jQuery
  描述：要取消綁定事件處理程序的元素。不像 _on() 方法，_off() 方法中元素是必需的。
• eventName
  類(lèi)型：String
  描述：一個(gè)或多個(gè)空格分隔的事件類(lèi)型。

代碼實(shí)例：

從小部件的元素上取消綁定所有 click 事件。

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

• 保持處理程序內(nèi)適當(dāng)?shù)?this 上下文。
• 自動(dòng)處理禁用的部件：如果小部件被禁用或事件發(fā)生在帶有 ui-state-disabled class 的元素上，則不調(diào)用事件處理程序?？梢员?suppressDisabledCheck 參數(shù)重寫(xiě)。
• 事件處理程序會(huì)自動(dòng)添加命名空間，在銷(xiāo)毀時(shí)會(huì)自自動(dòng)清理。
• suppressDisabledCheck（默認(rèn)值：false）
  類(lèi)型：Boolean
  描述：是否要繞過(guò)禁用的檢查。
• element
  類(lèi)型：jQuery
  描述：要綁定事件處理程序的元素。如果未提供元素，this.element 用于未授權(quán)的事件，widget 元素 用于授權(quán)的事件。
• handlers
  類(lèi)型：Object
  描述：一個(gè) map，其中字符串鍵代表事件類(lèi)型，可選的選擇器用于授權(quán)，值代表事件調(diào)用的處理函數(shù)。

代碼實(shí)例：

放置小部件元素內(nèi)所有被點(diǎn)擊的鏈接的默認(rèn)行為。

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

• key
  類(lèi)型：String
  描述：要設(shè)置的選項(xiàng)名稱。
• value
  類(lèi)型：Object
  描述：為選項(xiàng)設(shè)置的值。

代碼實(shí)例：

當(dāng)小部件的 height 或 width 選項(xiàng)改變時(shí)，更新小部件的元素。

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

• options
  類(lèi)型：Object
  描述：為選項(xiàng)設(shè)置的值。

代碼實(shí)例：

如果小部件的 height 或 width 選項(xiàng)改變，調(diào)用 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
  類(lèi)型：jQuery
  描述：要顯示的元素。
• option
  類(lèi)型：Object
  描述：定義如何顯示元素的設(shè)置。
• callback
  類(lèi)型：Function()
  描述：元素完全顯示后要調(diào)用的回調(diào)。

代碼實(shí)例：

為自定義動(dòng)畫(huà)傳遞 show 選項(xiàng)。

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

• arg
  類(lèi)型：Object
  描述：要傳遞給父部件的方法的零到多個(gè)參數(shù)。

代碼實(shí)例：

處理 title 選項(xiàng)更新，并調(diào)用付部件的 _setOption() 來(lái)更新選項(xiàng)的內(nèi)部存儲(chǔ)。

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

• arguments
  類(lèi)型：Array
  描述：要傳遞給父部件的方法的參數(shù)數(shù)組。

代碼實(shí)例：

處理 title 選項(xiàng)更新，并調(diào)用付部件的 _setOption() 來(lái)更新選項(xiàng)的內(nèi)部存儲(chǔ)。

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

事件名稱是小部件名稱和類(lèi)型的小寫(xiě)字母串。

注釋：當(dāng)提供數(shù)據(jù)時(shí)，您必須提供所有三個(gè)參數(shù)。如果沒(méi)有傳遞事件，則傳遞 null。

如果默認(rèn)行為是阻止的，則返回 false，否則返回 true。當(dāng)處理程序返回 false 時(shí)或調(diào)用 event.preventDefault() 時(shí)，則阻止默認(rèn)行為發(fā)生。

• type
  類(lèi)型：String
  描述：type 應(yīng)該匹配回調(diào)選項(xiàng)的名稱。完整的事件類(lèi)型會(huì)自動(dòng)生成。
• event
  類(lèi)型：Event
  描述：導(dǎo)致該事件發(fā)生的原始事件，想聽(tīng)眾提供上下文時(shí)很有用。
• data
  類(lèi)型：Object
  描述：一個(gè)與事件相關(guān)的數(shù)據(jù)哈希。

代碼實(shí)例：

當(dāng)按下一個(gè)鍵時(shí)，觸發(fā) 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()
    });
  }
});
	

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

當(dāng)點(diǎn)擊小部件的任意錨點(diǎn)時(shí)銷(xiāo)毀小部件。

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

當(dāng)點(diǎn)擊小部件的任意錨點(diǎn)時(shí)禁用小部件。

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

當(dāng)點(diǎn)擊小部件的任意錨點(diǎn)時(shí)啟用小部件。

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

• optionName
  類(lèi)型：String
  描述：要獲取的選項(xiàng)的名稱。

代碼實(shí)例：

獲得 width 選項(xiàng)的值。

this.option( "width" );
	

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

記錄每個(gè)小部件選項(xiàng)的鍵/值對(duì)，用于調(diào)試。

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

• optionName
  類(lèi)型：String
  描述：要設(shè)置的選項(xiàng)的名稱。
• value
  類(lèi)型：Object
  描述：要為選項(xiàng)設(shè)置的值。

代碼實(shí)例：

設(shè)置 width 選項(xiàng)為 500。

this.option( "width", 500 );
	

• options
  類(lèi)型：Object
  描述：要設(shè)置的 option-value 對(duì)。

代碼實(shí)例：

設(shè)置 height 和 width 選項(xiàng)為 500。

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

• 該方法不接受任何參數(shù)。

代碼實(shí)例：

當(dāng)創(chuàng)建小部件時(shí)，在小部件的原始元素周?chē)胖靡粋€(gè)紅色的邊框。

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

• event
  類(lèi)型：Event
• ui
  類(lèi)型：Object

注意：ui 對(duì)象是空的，這里包含它是為了與其他事件保持一致性。

代碼實(shí)例：

初始化帶有指定 create 回調(diào)的小部件：

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

綁定一個(gè)事件監(jiān)聽(tīng)器到 widgetcreate 事件：

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