jQuery UI API開發人員指南，jqueryuiapi開發人員

jQuery UI API開發人員指南，jqueryuiapi開發人員

原文地址：

http://jqueryui.com/docs/Developer_Guide

 

 組件工廠(The widget factory)

 

ui.core.js提供了一個Factory 方法來建立組件類。通過$ .widget(String name, Options prototype)標識。

 

調用工廠建立組件的方法，來建立一個組件類的執行個體或者與一個組件執行個體互動。

 

除了那些原型提供的方法，每個執行個體都還可以使用下面的預設方法：

• destroy(): 從DOM的元素中移除建立的執行個體
• getData/setData/data(String key[, String value]): 為執行個體擷取或設定一個選項
• enable(): 設定disabled選項為false, its up to the instance to respect the option
• disable(): 設定disabled選項為true, its up to the instance to respect the option

 每個執行個體都可以使用的屬性：

• options: 組件執行個體的選項,通常是由使用者提供的一些組合的預設選項
• element: 一個jQuery object總是包含一個單一的DOMElement，可以通過這樣的方法獲得：this.element[0].

在你的組件代碼當中，你可以重寫這些方法，如果你想“繼承”這些方法，並且增加一些功能，那麼這樣做：

$.widget.prototype.methodToOverride.apply(this, arguments);

會執行預設的方法。那麼你可以增加你自己定製的代碼。

 

指令碼：

$.widget("ui.mywidget", { _init: function() { // mywidget的初始化代碼 // 可以使用this.options if (this.options.hidden) { // 和this.element this.element.hide(); } }, _doSomething: function() { // 內建函式的命名應當以底線開頭 // 操作這個組件 }, value: function() { // 計算一些值並返回 return this._calculate(); }, length: function() { return this._someOtherValue(); }, destroy: function() { $.widget.prototype.apply(this, arguments); // 預設銷毀 // 再做一些這個組件特殊的事情 } }); $.extend($.ui.mywidget, { getter: "value length", defaults: { option1: "defaultValue", hidden: true } });

任何jQuery UI 組件都使用組件工廠，更完全的例子，可以隨便找一個外掛程式的全部的原始碼來研究，例如ui.progressbar.js.

 

一個關於編寫UI組件更全面的教程，請開啟連結。

 

屬性的設定和擷取

 

組件初始化元素時，編碼者可以傳遞選項覆蓋預設的選項。

$("div").draggable({ helper: "clone", axis: "x" });

上面的代碼中，會使所有的div變成可拖動物件，除了helper 和xis，具有預設的選項。但一旦當一個元素被建立後，所有其他的對組件名稱的調用，如果第一個參數不是string會被忽略，所以它不能被用作在執行個體被初始化之後設定選項。

關於這點，擷取和設定屬性需要通過組件的option方法。舉個例子，改變draggable的axis為 'y'，需要這樣設定：

$("div").draggable("option", "axis", "y");  

[譯者：而不是上面那種方法來設定屬性]

而擷取一個選項值，需要通過：

var saveAxis = $("div").draggable("option", "axis");

組件通過綁定一些定製的事件到元素上來建立這些功能。如果你想監聽這些設定或擷取動作，你可以重寫setData/getData函數在組件原型定義中，就像這樣：

setData: function(key, value) { }, getData: function(key) { }

那麼內部的 $(...).data() 函數觸發那些事件，去看一下是否應該重寫它的預設行為，設定或返回值。

 

內建函式和應用說明

jQuery.data / jQuery.fn.data

 

組件開發人員經常會需要為DOM節點增加所謂的擴充，這意味著DOM節點需要儲存額外的資料，這經常會產生記憶體泄露。

jQuery有它自己的方法來解決--data函數。它會為每一個節點建立一個特製的string並使用它來儲存資料,所以不會產生循環參考。

你組件的執行個體由組件工廠通過關鍵字'widget'來自動儲存（widget替換成你的組件名稱）：

this.element.data("draggable") === this;

或者

jQuery.data(this.element[0], "draggable") === this

 

 這個例子也被UI framework用作跟蹤節點中一個組件是否被建立。UI會允許每個節點組件被建立多次，刪除一個執行個體如下：

removeData("myWidgetName")

更多資訊請參考Internals/jQuery.data

 

jQuery.fn

jQuery.fn是jQuery最普通的外掛程式存放處，