Widget Factory · jQuery UI API 中文文檔 1.10

# Widget Factory Categories: [Utilities](http://www.css88.com/jquery-ui-api/category/utilities/ "View all posts in Utilities") | [Widgets](http://www.css88.com/jquery-ui-api/category/widgets/ "View all posts in Widgets") * [jQuery.widget( name [, base ], prototype )](#jQuery-widget1) * [jQuery.widget( name [, base ], prototype )](#jQuery-widget-name-base-prototype) * [jQuery.Widget](#jQuery-Widget2) ## jQuery.widget( name [, base ], prototype ) **Description:** 使用與所有 jQuery UI 小部件相同的抽象化來創建有狀態的 jQuery 插件。 * #### [jQuery.widget( name [, base ], prototype )](#jQuery-widget-name-base-prototype) * **name**Type: [String](http://api.jquery.com/Types/#String)要創建的小部件名稱，包括命名空間。 * **base**Type: [Function](http://api.jquery.com/Types/#Function)()要繼承的基礎小部件。必須是一個可以使用 `new` 關鍵詞實例化的構造函數。默認為 `jQuery.Widget`。 * **prototype**Type: [PlainObject](http://api.jquery.com/Types/#PlainObject)要作為小部件原型使用的對象。您可以使用 `$.Widget` 對象作為要繼承的基礎，或者可以明確地從現有的 jQuery UI 或第三方控件，從頭開始創建新的小部件。定義一個帶有相同名稱的小部件來繼承基礎部件，甚至允許您適當地擴展小部件。 jQuery UI 中包含許多保持狀態的小部件，因此比典型的 jQuery 插件稍有不同的使用模式。所有的jQuery UI 小部件使用相同的模式，這是由部件庫（Widget Factory）定義的。所以，只要您學會使用其中一個，您就知道如何使用其他的小部件（Widget）。尋找有關小部件工廠的教程？查看[jQuery學習中心的文章](http://learn.jquery.com/jquery-ui/widget-factory/)。注意：本章節使用 [進度條部件（Progressbar Widget）](/progressbar/) 演示實例，但是語法適用于每個小部件。 ### 初始化為了跟蹤小部件的狀態，我們必須引入小部件的全生命周期。小部件初始化時生命周期開始。要初始化一個小部件，我們只需要簡單地在一個或多個元素上調用插件。 ``` $( "#elem" ).progressbar(); ``` 這將初始化 jQuery 對象中的每個元素。上面實例中元素 id 為 `"elem"`。 ### 選項由于 `progressbar()` 調用時不帶參數，小部件是使用默認選項進行初始化的。我們可以在初始化時傳遞一組選項來覆蓋默認選項： ``` $( "#elem" ).progressbar({ value: 20 }); ``` 我們可以根據需要傳遞選項的個數，任何我們未傳遞的選項都使用它們的默認值。您可以傳遞多個選項參數，這些參數將會被合并為一個對象（類似于 [`$.extend( true, target, object1, objectN )`](//api.jquery.com/jQuery.extend/)）。這在為所有實例覆蓋一些設置，實例間共享選項時很有用： ``` var options = { modal: true, show: "slow" }; $( "#dialog1" ).dialog( options ); $( "#dialog2" ).dialog( options, { autoOpen: false }); ``` 所有在初始化時傳遞的選項都是深拷貝的，確保后續在不影響小部件的情況下修改對象。數組是唯一的例外，它們是按原樣引用的。這個例外是為了適當地支持數據綁定，其中數據源必須作為引用。默認值保存在小部件的屬性中，因此我們可以覆蓋 jQuery UI 設置的值。例如，在下面的設置后，所有將來的進度條實例將默認為值 80： ``` $.ui.progressbar.prototype.options.value = 80; ``` 選項是小部件狀態的組成部分，所以我們也可以在初始化后設置選項。我們會在后續看到 option 方法。 ### 方法現在小部件已經初始化，我們可以查詢它的狀態，或者在小部件上執行動作。所有初始化后的動作都是以方法調用方式執行。為了在小部件上調用一個方法，我們向 jQuery 插件傳遞方法的名稱。例如，在進度條部件（Progressbar Widget）上調用 `value()` 方法，我們可以使用： ``` $( "#elem" ).progressbar( "value" ); ``` 如果方法接受參數，我們可以在方法名稱后傳遞參數。例如，要傳遞參數 `40` 到 `value()` 方法，我們可以使用： ``` $( "#elem" ).progressbar( "value", 40 ); ``` 就像 jQuery 中的其他方法，大多數的小部件方法返回 jQuery 對象： ``` $( "#elem" ) .progressbar( "value", 90 ) .addClass( "almost-done" ); ``` 每個小部件都有自己的方法設置，這些設置是基于小部件提供的功能。但是，有一些方法是存在于所有的小部件上，這會在下面進行詳細講解。 ### 事件所有的小部件都有與它們各種行為相關的事件，以便在狀態改變的時候通知您。對于大多數的小部件，當事件被觸發時，名稱以小部件名稱的小寫字母形式作為前綴。例如，我們可以綁定進度條的 `change` 事件，該事件在值改變時觸發。 ``` $( "#elem" ).bind( "progressbarchange", function() { alert( "The value has changed!" ); }); ``` 每個事件都有一個對應的回調，這會作為選項。如果需要，我們可以抓住進度條的 `change` 回調，而不用綁定 `progressbarchange` 事件。 ``` $( "#elem" ).progressbar({ change: function() { alert( "The value has changed!" ); } }); ``` 所有的小部件都有一個 `change` 事件，該事件在實例化時觸發。 ### 實例化小部件的實例是使用帶有小部件全稱作為鍵的 [`jQuery.data()`](//api.jquery.com/jQuery.data/) 存儲的。因此，您可以使用下面代碼從元素檢索進度條部件（Progressbar Widget）的實例對象。 ``` $( "#elem" ).data( "ui-progressbar" ); ``` 元素是否綁定了給定小部件，可以使用 [`:data`](/data-selector/) 選擇器來檢測。 ``` $( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false ``` 您也可以使用 `:data` 來獲得作為給定小部件實例的所有元素的列表。 ``` $( ":data( 'ui-progressbar' )" ); ``` ### 屬性所有的小部件都有下面的屬性： * **defaultElement**：當構造小部件實例未提供元素時要使用的元素。例如，由于進度條的 `defaultElement` 是 `"<div>`"，`$.ui.progressbar({ value: 50 })` 在一個新建的 `<div>` 上實例化進度條小部件實例。 * **document**：其內包含小部件元素的 `document`。如果需要在框架內與小部件進行交互時很有用。 * **element**：一個 jQuery 對象，包含用于實例化小部件的元素。如果您選擇多個元素并調用 `.myWidget()`，將為每個元素創建一個單獨的小部件實例。因此，該屬性總是包含一個元素。 * **namespace**：小部件原型存儲的全局 jQuery 對象的位置。例如，`"ui"` 的 `namespace` 表示小部件原型存儲在 `$.ui`。 * **options**：一個包含小部件當前使用選項的對象。在實例化時，用戶提供的任何選項將會自動與 `$.myNamespace.myWidget.prototype.options` 中定義的默認值合并。用戶指定的選項會覆蓋默認值。 * **uuid**：一個表示控件標識符的唯一整數。 * **version**：小部件的字符串版本。對于 jQuery UI 小部件，該屬性會被設置為小部件使用的 jQuery UI 的版本。插件開發者必須在他們的原型中明確設置該屬性。 * **widgetEventPrefix**：添加到小部件事件名稱的前綴。例如，[可拖拽小部件（Draggable Widget）](/draggable/) 的 `widgetEventPrefix` 是 `"drag"`，因此當創建一個 draggable 時，事件的名稱是 `"dragcreate"`。默認情況下，小部件的 `widgetEventPrefix` 是它的名稱。_注意：該屬性已被廢棄，將在以后的版本中非常。事件名稱將被改為 widgetName:eventName （例如 `"draggable:create"`）。_ * **widgetFullName**：包含命名空間的小部件全稱。對于 `$.widget( "myNamespace.myWidget", {} )`， `widgetFullName` 將是 `"myNamespace-myWidget"`。 * **widgetName**：小部件的名稱。對于 `$.widget( "myNamespace.myWidget", {} )`，`widgetName` 將是 `"myWidget"`。 * **window**：其內包含小部件元素的 `window`。如果需要在框架內與小部件進行交互時很有用。 **Description:** 部件庫（Widget Factory）使用的基礎小部件。 ## QuickNav ### Options + [disabled](#option-disabled) + [hide](#option-hide) + [show](#option-show) ### Methods + [_create](#method-_create) + [_delay](#method-_delay) + [_destroy](#method-_destroy) + [_focusable](#method-_focusable) + [_getCreateEventData](#method-_getCreateEventData) + [_getCreateOptions](#method-_getCreateOptions) + [_hide](#method-_hide) + [_hoverable](#method-_hoverable) + [_init](#method-_init) + [_off](#method-_off) + [_on](#method-_on) + [_setOption](#method-_setOption) + [_setOptions](#method-_setOptions) + [_show](#method-_show) + [_super](#method-_super) + [_superApply](#method-_superApply) + [_trigger](#method-_trigger) + [destroy](#method-destroy) + [disable](#method-disable) + [enable](#method-enable) + [option](#method-option) + [widget](#method-widget) ### Events + [create](#event-create) ## Options ### disabled**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) **Default:** `false`如果設置為 `true`，則禁用該小部件。**Code examples:** 初始化帶有指定 `disabled` 選項的小部件： ``` $( ".selector" ).widget({ disabled: true }); ``` 在初始化后，獲取或設置`disabled` 選項： ``` // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); ``` ### hide**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) or [Object](http://api.jquery.com/Types/#Object) **Default:** `null`是否使用動畫隱藏元素，以及如何動畫隱藏元素。**支持多個類型：** * **Boolean**：當設置為 `false` 時，則不使用動畫，元素會立即隱藏。當設置為 `true` 時，元素會使用默認的持續時間和默認的 easing 淡出。 * **Number**：元素將使用指定的持續時間和默認的 easing 淡出。 * **String**：元素將使用指定的特效隱藏。該值可以是一個內建的 jQuery 動畫方法名稱，比如 `"slideUp"`，也可以是一個 [jQuery UI 特效](/category/effects/) 的名稱，比如`"fold"`。以上兩種情況的特效將使用默認的持續時間和默認的 easing。 * **Object**：如果值是一個對象，則 `effect`、`delay`、`duration` 和 `easing` 屬性會被提供。如果 `effect` 屬性包含 jQuery 方法的名稱，則使用該方法，否則，它被認為是一個 jQuery UI 特效的名稱。當使用一個支持額外設置的 jQuery UI 特效時，您可以在對象中包含這些設置，且它們會被傳遞給特效。如果 `duration` 或 `easing` 被省略，則使用默認值。如果 `effect` 被省略，則使用 `"fadeOut"`。如果 `delay` 被省略，則不使用延遲。 **Code examples:** 初始化帶有指定 `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 } ); ``` ### show**Type:** [Boolean](http://api.jquery.com/Types/#Boolean) or [Number](http://api.jquery.com/Types/#Number) or [String](http://api.jquery.com/Types/#String) or [Object](http://api.jquery.com/Types/#Object) **Default:** `null`是否使用動畫顯示元素，以及如何動畫顯示元素。**支持多個類型：** * **Boolean**：當設置為 `false` 時，則不使用動畫，元素會立即顯示。當設置為 `true` 時，元素會使用默認的持續時間和默認的 easing 淡入。 * **Number**：元素將使用指定的持續時間和默認的 easing 淡入。 * **String**：元素將使用指定的特效顯示。該值可以是一個內建的 jQuery 動畫方法名稱，比如 `"slideDown"`，也可以是一個 [jQuery UI 特效](/category/effects/) 的名稱，比如`"fold"`。以上兩種情況的特效將使用默認的持續時間和默認的 easing。 * **Object**：如果值是一個對象，則 `effect`、`delay`、`duration` 和 `easing` 屬性會被提供。如果 `effect` 屬性包含 jQuery 方法的名稱，則使用該方法，否則，它被認為是一個 jQuery UI 特效的名稱。當使用一個支持額外設置的 jQuery UI 特效時，您可以在對象中包含這些設置，且它們會被傳遞給特效。如果 `duration` 或 `easing` 被省略，則使用默認值。如果 `effect` 被省略，則使用 `"fadeIn"`。如果 `delay` 被省略，則不使用延遲。 **Code examples:** 初始化帶有指定 `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 } ); ``` ## Methods ### _create()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) `_create()` 方法是小部件的構造函數。沒有參數，但是 `this.element` 和 `this.options` 已經設置。 * 該方法不接受任何參數。 **Code examples:** 基于一個選項設置小部件元素的背景顏色。 ``` _create: function() { this.element.css( "background-color", this.options.color ); } ``` ### _delay( fn [, delay ] )Returns: [Number](http://api.jquery.com/Types/#Number) 在指定延遲后調用提供的函數。保持 `this` 上下文正確。本質上是 `setTimeout()`。使用 `clearTimeout()` 返回超時 ID。 * **fn**Type: [Function](http://api.jquery.com/Types/#Function)() or [String](http://api.jquery.com/Types/#String)要調用的函數。也可以是小部件上方法的名稱。 * **delay**Type: [Number](http://api.jquery.com/Types/#Number)調用函數前等待的毫秒數，默認為 `0`。 **Code examples:** 100 毫秒后在小部件上調用 `_foo()` 方法。 ``` this._delay( this._foo, 100 ); ``` ### _destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 公共的 [`destroy()`](#method-destroy) 方法清除所有的公共數據、事件等等。代表了定制、指定小部件、清理的 `_destroy()`。 * 該方法不接受任何參數。 **Code examples:** 當小部件被銷毀時，從小部件的元素移除一個 class。 ``` _destroy: function() { this.element.removeClass( "my-widget" ); } ``` ### _focusable( element )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 建立聚焦在元素上時要應用 `ui-state-focus` 的 `element`。事件處理程序在銷毀時自動清理。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要應用 focusable 行為的元素。 **Code examples:** 向小部件內的一組元素應用 focusable 樣式： ``` this._focusable( this.element.find( ".my-items" ) ); ``` ### _getCreateEventData()Returns: [Object](http://api.jquery.com/Types/#Object) 所有的小部件觸發 [`create`](#event-create) 事件。默認情況下，事件中不提供任何的數據，但是該方法會返回一個對象，作為 `create` 事件的數據被傳遞。 * 該方法不接受任何參數。 **Code examples:** 向 `create` 事件處理程序傳遞小部件的選項，作為參數。 ``` _getCreateEventData: function() { return this.options; } ``` ### _getCreateOptions()Returns: [Object](http://api.jquery.com/Types/#Object) 該方法允許小部件在初始化期間為定義選項定義一個自定義的方法。用戶提供的選項會覆蓋該方法返回的選項，即會覆蓋默認的選項。 * 該方法不接受任何參數。 **Code examples:** 讓小部件元素的 id 屬性作為選項可用。 ``` _getCreateOptions: function() { return { id: this.element.attr( "id" ) }; } ``` ### _hide( element, option [, callback ] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 使用內置的動畫方法或使用自定義的特效隱藏一個元素。如需了解可能的 `option` 值，請查看 [hide](#option-hide)。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要隱藏的元素。 * **option**Type: [Object](http://api.jquery.com/Types/#Object)定義如何隱藏元素的設置。 * **callback**Type: [Function](http://api.jquery.com/Types/#Function)()元素完全隱藏后要調用的回調。 **Code examples:** 為自定義動畫傳遞 `hide` 選項。 ``` this._hide( this.element, this.options.hide, function() { // Remove the element from the DOM when it's fully hidden. $( this ).remove(); }); ``` ### _hoverable( element )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 建立懸浮在元素上時要應用 `ui-state-hover` class 的 `element`。事件處理程序在銷毀時自動清理。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要應用 hoverable 行為的元素。 **Code examples:** 當懸浮在元素上時，向元素內所有的 `<div>` 應用 hoverable 樣式。 ``` this._hoverable( this.element.find( "div" ) ); ``` ### _init()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 小部件初始化的理念與創建不同。任何時候不帶參數的調用插件或者只帶一個選項哈希的調用插件，初始化小部件。當小部件被創建時會包含這個方法。 _注意：如果存在不帶參數成功調用小部件時要執行的邏輯動作，初始化只能在這時處理。_ * 該方法不接受任何參數。 **Code examples:** 如果設置了 `autoOpen` 選項，則調用 `open()` 方法。 ``` _init: function() { if ( this.options.autoOpen ) { this.open(); } } ``` ### _off( element, eventName )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 從指定的元素取消綁定事件處理程序。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要取消綁定事件處理程序的元素。不像 `_on()` 方法，`_off()` 方法中元素是必需的。 * **eventName**Type: [String](http://api.jquery.com/Types/#String)一個或多個空格分隔的事件類型。 **Code examples:** 從小部件的元素上取消綁定所有 click 事件。 ``` this._off( this.element, "click" ); ``` ### _on( [suppressDisabledCheck ] [, element ], handlers )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 授權通過事件名稱內的選擇器被支持，例如 "`click .foo`"。`_on()` 方法提供了一些直接事件綁定的好處： * 保持處理程序內適當的 `this` 上下文。 * 自動處理禁用的部件：如果小部件被禁用或事件發生在帶有 `ui-state-disabled` class 的元素上，則不調用事件處理程序。可以被 `suppressDisabledCheck` 參數重寫。 * 事件處理程序會自動添加命名空間，在銷毀時會自自動清理。 * **suppressDisabledCheck** (default: `false`)Type: [Boolean](http://api.jquery.com/Types/#Boolean)是否要繞過禁用的檢查。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要綁定事件處理程序的元素。如果未提供元素，`this.element` 用于未授權的事件， [widget 元素](#method-widget) 用于授權的事件。 * **handlers**Type: [Object](http://api.jquery.com/Types/#Object)一個 map，其中字符串鍵代表事件類型，可選的選擇器用于授權，值代表事件調用的處理函數。 **Code examples:** 放置小部件元素內所有被點擊的鏈接的默認行為。 ``` this._on( this.element, { "click a": function( event ) { event.preventDefault(); } }); ``` ### _setOption( key, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 為每個獨立的選項調用 [`_setOptions()`](#method-_setOptions) 方法。小部件狀態隨著改變而更新。 * **key**Type: [String](http://api.jquery.com/Types/#String)要設置的選項名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)為選項設置的值。 **Code examples:** 當小部件的 `height` 或 `width` 選項改變時，更新小部件的元素。 ``` _setOption: function( key, value ) { if ( key === "width" ) { this.element.width( value ); } if ( key === "height" ) { this.element.height( value ); } this._super( key, value ); } ``` ### _setOptions( options )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 當調用 [`option()`](#method-option) 方法時調用，無論以什么形式調用 `option()`。如果您要根據多個選項的改變而改變處理器密集型，重載該方法是很有用的。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的選項-值對。 **Code examples:** 如果小部件的 `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(); } } ``` ### _show( element, option [, callback ] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 使用內置的動畫方法或使用自定義的特效顯示一個元素。如需了解可能的 `option` 值，請查看 [show](#option-show)。 * **element**Type: [jQuery](http://api.jquery.com/Types/#jQuery)要顯示的元素。 * **option**Type: [Object](http://api.jquery.com/Types/#Object)定義如何顯示元素的設置。 * **callback**Type: [Function](http://api.jquery.com/Types/#Function)()元素完全顯示后要調用的回調。 **Code examples:** 為自定義動畫傳遞 `show` 選項。 ``` this._show( this.element, this.options.show, function() { // Focus the element when it's fully visible. this.focus(); } ``` ### _super( [arg ] [, ... ] )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 從父部件中調用相同名稱的方法，帶有任意指定的參數。本質上是`.call()`。 * **arg**Type: [Object](http://api.jquery.com/Types/#Object)要傳遞給父部件的方法的零到多個參數。 **Code examples:** 處理 `title` 選項更新，并調用付部件的 `_setOption()` 來更新選項的內部存儲。 ``` _setOption: function( key, value ) { if ( key === "title" ) { this.element.find( "h3" ).text( value ); } this._super( key, value ); } ``` ### _superApply( arguments )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 從父部件中調用相同名稱的方法，帶有參數的數組。本質上是 `.apply()`。 * **arguments**Type: [Array](http://api.jquery.com/Types/#Array)要傳遞給父部件的方法的參數數組。 **Code examples:** 處理 `title` 選項更新，并調用付部件的 `_setOption()` 來更新選項的內部存儲。 ``` _setOption: function( key, value ) { if ( key === "title" ) { this.element.find( "h3" ).text( value ); } this._superApply( arguments ); } ``` ### _trigger( type [, event ] [, data ] )Returns: [Boolean](http://api.jquery.com/Types/#Boolean) 觸發一個事件及其相關的回調。帶有該名稱的選項與作為回調被調用的類型相等。事件名稱是小部件名稱和類型的小寫字母串。 _注意: 當提供數據時，您必須提供所有三個參數。如果沒有傳遞事件，則傳遞 `null`。_ 如果默認行為是阻止的，則返回 `false`，否則返回 `true`。當處理程序返回 `false` 時或調用 `event.preventDefault()` 時，則阻止默認行為發生。 * **type**Type: [String](http://api.jquery.com/Types/#String)The `type` 應該匹配回調選項的名稱。完整的事件類型會自動生成。 * **event**Type: [Event](http://api.jquery.com/Types/#Event)導致該事件發生的原始事件，想聽眾提供上下文時很有用。 * **data**Type: [Object](http://api.jquery.com/Types/#Object)一個與事件相關的數據哈希。 **Code examples:** 當按下一個鍵時，觸發 `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() }); } }); ``` ### destroy()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 完全移除小部件功能。這會把元素返回到它的預初始化狀態。 * 該方法不接受任何參數。 **Code examples:** 當點擊小部件的任意錨點時銷毀小部件。 ``` this._on( this.element, { "click a": function( event ) { event.preventDefault(); this.destroy(); } }); ``` ### disable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 禁用小部件。 * 該方法不接受任何參數。 **Code examples:** 當點擊小部件的任意錨點時禁用小部件。 ``` this._on( this.element, { "click a": function( event ) { event.preventDefault(); this.disable(); } }); ``` ### enable()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 啟用小部件。 * 該方法不接受任何參數。 **Code examples:** 當點擊小部件的任意錨點時啟用小部件。 ``` this._on( this.element, { "click a": function( event ) { event.preventDefault(); this.enable(); } }); ``` ### option( optionName )Returns: [Object](http://api.jquery.com/Types/#Object) 獲取當前與指定的 `optionName` 關聯的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要獲取的選項的名稱。 **Code examples:** 獲得 `width` 選項的值。 ``` this.option( "width" ); ``` ### option()Returns: [PlainObject](http://api.jquery.com/Types/#PlainObject) 獲取一個包含鍵/值對的對象，鍵/值對表示當前小部件選項哈希。 * 該方法不接受任何參數。 **Code examples:** Log the key and value of each of the widget's options for debugging. ``` var options = this.option(); for ( var key in options ) { console.log( key, options[ key ] ); } ``` ### option( optionName, value )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 設置與指定的 `optionName` 關聯的小部件選項的值。 * **optionName**Type: [String](http://api.jquery.com/Types/#String)要設置的選項的名稱。 * **value**Type: [Object](http://api.jquery.com/Types/#Object)要為選項設置的值。 **Code examples:** 設置 `width` 選項為 `500`。 ``` this.option( "width", 500 ); ``` ### option( options )Returns: [jQuery](http://api.jquery.com/Types/#jQuery) ([plugin only](http://learn.jquery.com/jquery-ui/widget-factory/widget-method-invocation/)) 為小部件設置一個或多個選項。 * **options**Type: [Object](http://api.jquery.com/Types/#Object)要設置的 option-value 對。 **Code examples:** 設置 `height` 和 `width` 選項為 `500`。 ``` this.option({ width: 500, height: 500 }); ``` ### widget()Returns: [jQuery](http://api.jquery.com/Types/#jQuery) 返回一個包含原始元素或其他相關的生成元素的 `jQuery` 對象。 * 該方法不接受任何參數。 **Code examples:** 當創建小部件時，在小部件的原始元素周圍放置一個紅色的邊框。 ``` _create: function() { this.widget().css( "border", "2px solid red" ); } ``` ## Events ### create( event, ui )Type: `widgetcreate` 當小部件被創建時觸發。 * **event**Type: [Event](http://api.jquery.com/Types/#Event) * **ui**Type: [Object](http://api.jquery.com/Types/#Object) _Note: `ui` 對象是空的，這里包含它是為了與其他事件保持一致性。_ **Code examples:** 初始化帶有指定 create 回調的小部件： ``` $( ".selector" ).widget({ create: function( event, ui ) {} }); ``` 綁定一個事件監聽器到 widgetcreate 事件： ``` $( ".selector" ).on( "widgetcreate", function( event, ui ) {} ); ```