用 jQuery 寫過幾個專案之後,遲早會想把常用片段整理成自己的插件。jQuery 提供的擴充方式其實只有兩條路:替 jQuery 類別本身加上靜態方法(類別層級),或替 jQuery 物件加上可在選取結果鏈上呼叫的方法(物件層級)。本文把兩條路各自的做法、常見陷阱與最佳實務完整梳理一遍。
類別層級最直接的理解,就是往 jQuery 的命名空間裡掛一個函式。$.ajax() 就是最典型的例子——它不針對任何一組元素,而是提供一個獨立可用的工具。
jQuery.foo = function() {
alert('This is a test. This is only a test.');
};
jQuery.foo = function() {
alert('This is a test. This is only a test.');
};
jQuery.bar = function(param) {
alert('傳入的參數是 "' + param + '"。');
};
呼叫方式與一般函式相同:jQuery.foo()、jQuery.bar('baz'),有了別名後也能寫成 $.foo()、$.bar('baz')。
jQuery.extend({
foo: function() {
alert('This is a test. This is only a test.');
},
bar: function(param) {
alert('傳入的參數是 "' + param + '"。');
}
});
jQuery 命名空間雖然已經禁止大量 JavaScript 內建名稱,但外掛一多,仍難保 foo、bar 這類通用名字不會撞車。實務上的解法是再包一層自己的命名空間:
jQuery.myPlugin = {
foo: function() {
alert('This is a test. This is only a test.');
},
bar: function(param) {
alert('傳入的參數是 "' + param + '"。');
}
};
$.myPlugin.foo();
$.myPlugin.bar('baz');
包成命名空間後,函式本質上仍是全域的,但呼叫路徑多了前綴,碰撞機率大幅下降。
物件層級有兩種等價寫法,一是 $.fn.extend,二是直接指派給 $.fn.pluginName。兩者都建議包在立即執行函式中:
(function($) {
$.fn.extend({
pluginName: function(opt, callback) {
// 插件實作
}
});
})(jQuery);
// 或者
(function($) {
$.fn.pluginName = function() {
// 插件實作
};
})(jQuery);
外層傳入 jQuery、參數名用 $,這樣在插件內部就能安心使用 $ 而不必擔心與其他函式庫衝突,也不必每次都寫完整的 jQuery。
單一插件只該佔用一個名字。以下把插件命名為 hilight(本文沿用原始範例的拼字,實作時建議統一改成 highlight 以免日後混淆):
$.fn.hilight = function() {
// 插件實作
};
$('#myDiv').hilight();
如果想把實作拆成多個小函式,又不想增加額外的全域名稱,可以善用「函式也是物件」這個特性:把輔助函式掛成 hilight 的屬性,需要公開的才有意願暴露。
$.fn.hilight = function(options) {
var defaults = {
foreground: 'red',
background: 'yellow'
};
var opts = $.extend(defaults, options);
// 插件實作
};
$('#myDiv').hilight({ foreground: 'blue' });
把 defaults 從函式內部搬到函式物件上,使用者就能只改一行、不必每次傳參:
$.fn.hilight = function(options) {
// 第一個參數給空物件,避免覆蓋掉 defaults 本身
var opts = $.extend({}, $.fn.hilight.defaults, options);
// 插件實作
};
$.fn.hilight.defaults = {
foreground: 'red',
background: 'yellow'
};
// 使用者端只需一行
$.fn.hilight.defaults.foreground = 'blue';
公開預設值之後,三種用法可以並存:改一次全域預設、用預設呼叫、以及在呼叫當下用參數臨時覆寫。
把格式化邏輯獨立出來並公開,等於替你的插件開了一個擴充點——別人可以替你的插件再寫插件:
$.fn.hilight = function(options) {
return this.each(function() {
var $this = $(this);
var markup = $this.html();
markup = $.fn.hilight.format(markup);
$this.html(markup);
});
};
$.fn.hilight.format = function(txt) {
return '' + txt + '';
};
真實案例是 Cycle 輪播插件。滑動、淡入淡出、捲動等各種轉場效果多如牛毛,作者不可能全部內建,於是它公開了 $.fn.cycle.transitions 這個物件,讓使用者自行註冊轉場函式。這正是「可覆寫」設計的價值所在。
暴露得越多,介面就越難維持相容。判斷標準很簡單:不確定要不要公開的,就不要公開。需要私有輔助函式時,用閉包包住整個插件即可:
(function($) {
$.fn.hilight = function(options) {
debug(this);
// 插件實作
};
function debug($obj) {
if (window.console) {
window.console.log('hilight 選到的元素數:' + $obj.size());
}
}
})(jQuery);
debug 定義在閉包內,外部無從取得,也就不會污染全域;同時參數與語意都可以自由調整,不必背負相容性包袱。
如果頁面需要針對每個元素給不同參數,與 Metadata 插件搭配會省下大量設定:
var opts = $.extend({}, $.fn.hilight.defaults, options);
return this.each(function() {
var $this = $(this);
var o = $.meta ? $.extend({}, opts, $this.data()) : opts;
// 套用樣式
});
這段程式先檢測 Metadata 是否已安裝;有的話就把該元素上的資料合併進 options,並放在 extend 的最後一個參數,因此優先權最高。於是行為可以直接寫在標記中,例如讓某個 div 使用紅底白字、另一個只改前景色,最後再用一行 $('.hilight').hilight(); 一次套用。
(function($) {
$.fn.hilight = function(options) {
debug(this);
var opts = $.extend({}, $.fn.hilight.defaults, options);
return this.each(function() {
var $this = $(this);
var o = $.meta ? $.extend({}, opts, $this.data()) : opts;
$this.css({
backgroundColor: o.background,
color: o.foreground
});
var markup = $this.html();
markup = $.fn.hilight.format(markup);
$this.html(markup);
});
};
function debug($obj) {
if (window.console) {
window.console.log('hilight 選到的元素數:' + $obj.size());
}
}
$.fn.hilight.format = function(txt) {
return '' + txt + '';
};
$.fn.hilight.defaults = {
foreground: 'red',
background: 'yellow'
};
})(jQuery);
jQuery 提供的兩個擴充入口,差別只在擴充的對象:
jQuery.fn.extend(object):擴充 jQuery.prototype,為 jQuery 類別加上「成員函式」,所有選取出來的實例都能呼叫。jQuery.extend(object):為 jQuery 類別本身加上方法,可理解為靜態方法。關鍵事實是 jQuery.fn = jQuery.prototype。所以 $("#btn1") 得到的就是一個 jQuery 類別的實例,自然能用 fn 上定義的方法。舉例來說,想做一個「點擊就跳出目前內容」的輸入框插件:
$.fn.extend({
alertWhileClick: function(){
$(this).click(function(){
alert($(this).val());
});
}
});
$('#input1').alertWhileClick();
而靜態方法則像這樣加上去,之後在任何引入 jQuery 的地方都能直接使用:
$.extend({
add: function(a, b){ return a + b; }
});
$.add(3, 4); // 回傳 7
$ 當參數傳入。$.extend({}, defaults, options) 合併參數,並記得第一個參數給空物件。this.each(...),維持鏈式呼叫的習慣。把這些原則內化成反射動作,寫出來的插件自然既好維護,也容易被人 reuse。