jQuery UI 如何使用部件庫

jQuery UI 如何使用部件庫（Widget Factory）

在本節(jié)中，我們將介紹jQuery UI如何使用部件庫。

在下述的示例中，我們將創(chuàng)建一個進度條，這可以通過調用jQuery.widget()來完成，它帶有兩個參數：一個是要創(chuàng)建的插件名稱，一個是包含支持插件的函數的對象文字。當插件被調用時，它將創(chuàng)建一個新的插件實例，所有的函數都將在該實例的語境中被執(zhí)行。這與兩種重要方式的標準jQuery插件不同。首先，語境是一個對象，不是DOM元素。其次，語境總是一個單一的對象，不是一個集合。

$.widget( "custom.progressbar", {
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    }
});

插件的名稱必須包含命名空間，在這個實例中，我們使用了custom命名空間。您只能創(chuàng)建一層深的命名空間，因此，custom.progressbar是一個有效的插件名稱，而very.custom.progressbar不是一個有效的插件名稱。

我們看到部件庫（Widget Factory）為我們提供了兩個屬性。this.element是一個包含一個元素的jQuery對象。如果我們的插件在包含多個元素的jQuery對象上調用，則會為每個元素創(chuàng)建一個單獨的插件實例，且每個實例都會有自己的this.element。第二個屬性，this.options，是一個包含所有插件選項的鍵名/鍵值對的哈希（hash）。這些選項可以被傳給插件，如下所示：

$( "<div></div>" )
    .appendTo( "body" )
    .progressbar({ value: 20 });

當我們調用jQuery.widget()，它通過給jQuery.fn（用于創(chuàng)建標準插件的系統(tǒng)） 添加函數來擴展jQuery。所添加的函數名稱是基于您傳給jQuery.widget() 的名稱，不帶命名空間-"progressbar"。傳給插件的選項是在插件實例中獲取設置的值。如下面的實例所示，我們可以為任意一個選項指定默認值。當設計您的API時，您應該清楚你的插件的最常見的使用情況，以便您可以設置適當的默認值，且確保使所有的選項真正可選。

$.widget( "custom.progressbar", {
 
    // Default options.
    options: {
        value: 0
    },
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    }
});

調用插件方法

現在我們可以初始化我們的進度條，我們將通過在插件實例上調用方法來執(zhí)行動作。為了定義一個插件方法，我們只在我們傳給jQuery.widget()的對象中引用函數。我們也可以通過給函數名加下劃線前綴來定義"private"方法。

$.widget( "custom.progressbar", {
 
    options: {
        value: 0
    },
 
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    },
 
    // Create a public method.
    value: function( value ) {
 
        // No value passed, act as a getter.
        if ( value === undefined ) {
            return this.options.value;
        }
 
        // Value passed, act as a setter.
        this.options.value = this._constrain( value );
        var progress = this.options.value + "%";
        this.element.text( progress );
    },
 
    // Create a private method.
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {           
 value = 0;         }         
return value;   
  } 
}); 

為了在插件實例上調用方法，您可以向jQuery插件傳遞方法的名稱。如果您調用的方法接受參數，您只需簡單地在方法名后面?zhèn)鬟f這些參數即可。

注意：通過向同一個用于初始化插件的jQuery函數傳遞方法名來執(zhí)行方法。這樣做是為了在保持鏈方法調用時防止jQuery命名空間污染。在本章節(jié)的后續(xù)，我們將看到看起來更自然的其他用法。

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar({ value: 20 });
 
// Get the current value.
alert( bar.progressbar( "value" ) );
 
// Update the value.
bar.progressbar( "value", 50 );
 
// Get the current value again.
alert( bar.progressbar( "value" ) );

使用選項

option()方法是自動提供給插件的。option()方法允許您在初始化后獲取并設置選項。該方法像jQuery的.css()和.attr()方法：您可以只傳遞一個名稱作為取值器來使用，也可以傳遞一個名稱和值作為設置器使用，或者傳遞一個鍵名/鍵值對的哈希來設置多個值。當作為取值器使用時，插件將返回與傳入名稱相對應的選項的當前值。當作為設置器使用時，插件的_setOption方法將被每個被設置的選項調用。我們可以在我們的插件中指定一個_setOption方法來反應選項更改。對于更改選項要獨立執(zhí)行的動作，我們可以重載_setOptions。

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {          
   value = 0;   
      } 
        return value;    
 } 
}); 

添加回調

最簡單的擴展插件的方法是添加回調，這樣用戶就可以在插件狀態(tài)發(fā)生變化時做出反應。我們可以看下面的實例如何在進度達到100%時添加回調到進度條。_trigger()方法有三個參數：回調名稱，一個啟動回調的jQuery事件對象，以及一個與事件相關的數據哈希?；卣{名稱是唯一一個必需的參數，但是對于想要在插件上實現自定義功能的用戶，其他的參數是非常有用的。例如，如果我們創(chuàng)建一個可拖拽插件，我們可以在觸發(fā)拖拽回調時傳遞mousemove事件，這將允許用戶對基于由事件對象提供的x/y坐標上的拖拽做出反應。請注意，傳遞到_trigger()的原始的事件必須是一個jQuery事件，而不是一個原生的瀏覽器事件。

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
        if ( this.options.value == 100 ) {
            this._trigger( "complete", null, { value: 100 } );
        }
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {  
           value = 0;       
  }  
       return value;  
   }
 }); 

回調函數本質上只是附加選項，所以您可以像其他選項一樣獲取并設置它們。無論何時執(zhí)行回調，都會有一個相對應的事件被觸發(fā)。事件類型是通過連接插件的名稱和回調函數名稱確定的?；卣{和事件都接受兩個相同的參數：一個事件對象和一個與事件相關的數據哈希，具體如下面實例所示。您的插件可能需要包含防止用戶使用的功能，為了做到這點，最好的方法就是創(chuàng)建可撤銷的回調。用戶可以撤銷回調或者相關的事件，與他們撤銷任何一個原生事件一樣，都是通過調用 event.preventDefault()或返回false來實現的。如果用戶撤銷回調，_trigger()方法將返回false，這樣您就能在插件內實現合適的功能。

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar({
        complete: function( event, data ) {
            alert( "Callbacks are great!" );
        }
    })
    .bind( "progressbarcomplete", function( event, data ) {
        alert( "Events bubble and support many handlers for extreme flexibility." );
        alert( "The progress bar value is " + data.value );
    });
 
bar.progressbar( "option", "value", 100 );

本質

現在我們已經看到如何使用部件庫（Widget Factory）創(chuàng)建一個插件，接下來讓我們看看它實際上是如何工作的。當您調用jQuery.widget()時，它將為插件創(chuàng)建一個構造函數，并設置您為插件實例傳入的作為原型的對象。所有自動添加到插件的功能都來自一個基本的小部件原型，該原型定義為jQuery.Widget.prototype。當創(chuàng)建插件實例時，會使用jQuery.data把它存儲在原始的DOM元素上，插件名作為鍵名。

由于插件實例直接鏈接到DOM元素上，您可以直接訪問插件實例，而不需要遍歷插件方法。這將允許您直接在插件實例上調用方法，而不需要傳遞字符串形式的方法名，同時您也可以直接訪問插件的屬性。

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar()
    .data( "progressbar" );
 
// Call a method directly on the plugin instance.
bar.option( "value", 50 );
 
// Access properties on the plugin instance.
alert( bar.options.value );
您也可以在不遍歷插件方法的情況下創(chuàng)建一個實例，通過選項和元素直接調用構造函數即可：
var bar = $.custom.progressbar( {}, $( "<div></div>" ).appendTo( "body") );
 
// Same result as before.
alert( bar.options.value );

擴展插件的原型

插件有構造函數和原型的最大好處是易于擴展插件。通過添加或修改插件原型上的方法，我們可以修改插件所有實例的行為。例如，如果我們想要向進度條添加一個方法來重置進度為0%，我們可以向原型添加這個方法，它將在所有插件實例上可調用。

$.custom.progressbar.prototype.reset = function() {
    this._setOption( "value", 0 );
};

如需了解擴展小部件的更多細節(jié)，以及如何在一個已有的小部件上創(chuàng)建一個全新的小部件的更多細節(jié)，請查看通過部件庫（Widget Factory）擴展小部件（Widget）。

清理

在某些情況下，允許用戶應用插件，然后再取消應用。您可以通過_destroy()方法做到這一點。在_destroy()方法內，您應該撤銷在初始化和后期使用期間插件所做的一切動作。_destroy()是通過.destroy()方法被調用的，.destroy()方法是在插件實例綁定的元素從DOM上移除時被自動調用的，所以這可被用于垃圾回收。基本的.destroy()方法也處理一些常用的清理操作，比如從小部件的DOM元素上移除實例引用，從元素上解除綁定小部件命名空間中的所有事件，解除綁定所有使用_bind()添加的事件。

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
        if ( this.options.value == 100 ) {
            this._trigger( "complete", null, { value: 100 } );
        }
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {     
        value = 0;     
    }
          return value;  
   },  
   _destroy: function() { 
        this.element          
   .removeClass( "progressbar" )         
    .text( "" );   
  }
 }); 

關閉注釋

部件庫（Widget Factory）只是創(chuàng)建有狀態(tài)插件的一種方式。這里還有一些其他不同的模型可以使用，且每個都有各自的優(yōu)勢和劣勢。部件庫（Widget Factory）解決了很多常見的問題，且大大提高了效率，同時也大大提高了代碼的重用性，使它適合于jQuery UI及其他有狀態(tài)的插件。

請注意，在本章節(jié)中我們使用了custom命名空間。ui命名空間被官方的jQuery UI插件保留。當創(chuàng)建您自己的插件時，您應該創(chuàng)建自己的命名空間。這樣才能更清楚插件來自哪里，屬于哪個范圍。