寫專案寫久了,總會遇到同一段程式碼被複製到第八個檔案裡的時刻。與其繼續複製,不如把它變成組件。本文從兩個層次談這件事:一是擴展既有組件,二是打造自己的組件。
ajax 呼叫大概長這樣:
$.ajax({
type: "post",
url: "/User/Edit",
data: { data: JSON.stringify(postdata) },
success: function (data, status) {
if (status == "success") {
toastr.success('提交數據成功');
$("#tb_aaa").bootstrapTable('refresh');
}
},
error: function (e) {},
complete: function () {}
});
問題來了:每寫一次就得附上一個空的 error: function(e){},但我其實希望每個請求失敗時都能把錯誤訊息顯示給使用者看。難道要在每個地方都寫一遍錯誤處理?
最直覺的做法是把 $.ajax({}) 再包一層,在這個公共方法裡定義 error。可行,但不完美:一是在 jQuery 之上再包一層,多繞一圈;二是改變了呼叫者的習慣,之後都得照我的規則寫,不能直接用原生的 $.ajax({})。
更好的做法是直接擴展原生的 $.ajax,讓呼叫方式完全不变。
(function ($) {
// 1. 保留原始的 $.ajax
var _ajax = $.ajax;
$.ajax = function (options) {
// 2. 定義預設的處理函式
var fn = {
error: function (XMLHttpRequest, textStatus, errorThrown) {
toastr.error(XMLHttpRequest.responseText, '錯誤消息', {
closeButton: true,
timeOut: 0,
positionClass: 'toast-top-full-width'
});
},
success: function (data, textStatus) {},
beforeSend: function (XHR) {},
complete: function (XHR, TS) {}
};
// 3. 呼叫者有自訂,就尊重呼叫者的
if (options.error) { fn.error = options.error; }
if (options.success) { fn.success = options.success; }
if (options.beforeSend){ fn.beforeSend = options.beforeSend; }
if (options.complete) { fn.complete = options.complete; }
// 4. 用 $.extend 把處理函式併回參數
var _options = $.extend(options, {
error: function (XMLHttpRequest, textStatus, errorThrown) {
fn.error(XMLHttpRequest, textStatus, errorThrown);
},
success: function (data, textStatus) {
fn.success(data, textStatus);
},
beforeSend: function (XHR) {
fn.beforeSend(XHR);
},
complete: function (XHR, TS) {
fn.complete(XHR, TS);
}
});
// 5. 交給原始方法執行
_ajax(_options);
};
})(jQuery);
讀不懂的話,先搞清 $.extend() 在做什麼。

官方文件給的兩個例子最能說明問題。
例一:
var settings = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
$.extend(settings, options);
結果:
settings == { validate: true, limit: 5, name: "bar" }
例二:
var empty = {};
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
var settings = $.extend(empty, defaults, options);
結果:
settings == { validate: true, limit: 5, name: "bar" }
empty == { validate: true, limit: 5, name: "bar" }
也就是說:合併多個物件,同名屬性由後者覆蓋,其餘照單全收。第一個參數是接收結果的目標物件,後面依序是被併入的来源。
理解這點,回頭看擴展 ajax 的程式碼就通了,步驟只有三步:
1. 定義一組預設的 error(以及 success、beforeSend、complete)處理函式。
2. 判斷呼叫者是否自訂了同名處理函式,有則覆蓋預設值。
3. 用 $.extend() 把這組函式併進 options,再交給原始的 ajax 執行。
對使用者來說完全無感:一樣寫 $.ajax({}),不特別處理錯誤時就有統一的提示。
擴展讓你能在既有組件上加入與自家業務相關的行為,而呼叫方式維持原樣,避免了「再包一層」帶來的臃腫。這比 fork 一份原始碼再改要好維護得多。
接著做一個簡單但具代表性的例子:把「從後端取資料填進 select」這件事封裝成 combobox。
(function ($) {
// 1. 定義 jQuery 擴展方法 combobox
$.fn.combobox = function (options, param) {
if (typeof options == 'string') {
return $.fn.combobox.methods[options](this, param);
}
// 2. 合併預設參數與使用者參數
options = $.extend({}, $.fn.combobox.defaults, options || {});
// 3. 寫入初始狀態
var target = $(this);
target.attr('valuefield', options.valueField);
target.attr('textfield', options.textField);
target.empty();
var option = $('<option></option>');
option.attr('value', '');
option.text(options.placeholder);
target.append(option);
// 4. 有 data 用 data,否則發 ajax
if (options.data) {
init(target, options.data);
} else {
options.onBeforeLoad.call(target, options.param);
if (!options.url) return;
$.getJSON(options.url, options.param, function (data) {
init(target, data);
});
}
function init(target, data) {
$.each(data, function (i, item) {
var option = $('<option></option>');
option.attr('value', item[options.valueField]);
option.text(item[options.textField]);
target.append(option);
});
options.onLoadSuccess.call(target);
}
target.unbind("change");
target.on("change", function (e) {
if (options.onChange) return options.onChange(target.val());
});
};
// 5. 對外方法
$.fn.combobox.methods = {
getValue: function (jq) {
return jq.val();
},
setValue: function (jq, param) {
jq.val(param);
},
load: function (jq, url) {
$.getJSON(url, function (data) {
jq.empty();
var option = $('<option></option>');
option.attr('value', '');
option.text('請選擇');
jq.append(option);
$.each(data, function (i, item) {
var option = $('<option></option>');
option.attr('value', item[jq.attr('valuefield')]);
option.text(item[jq.attr('textfield')]);
jq.append(option);
});
});
}
};
// 6. 預設參數
$.fn.combobox.defaults = {
url: null,
param: null,
data: null,
valueField: 'value',
textField: 'text',
placeholder: '請選擇',
onBeforeLoad: function (param) {},
onLoadSuccess: function () {},
onChange: function (value) {}
};
})(jQuery);
用法一:遠端取資料並初始化
<select id="sel_search_plant" class="form-control"></select>
$(function () {
$('#sel_search_plant').combobox({
url: '/apiaction/Plant/Find',
valueField: 'TM_PLANT_ID',
textField: 'NAME_C'
});
});
用法二:取值與設值
var strSelectedValue = $('#sel_search_plant').combobox("getValue");
$('#sel_search_plant').combobox("setValue", "aaa");
坦白說,對一個原生 select 而言,getValue / setValue 意義不大——直接 $('#sel_search_plant').val() 就能解決。這裡只是為了示範「字串參數代表呼叫方法」這個模式。如果封裝的是 select2 或 multiselect 這類複合組件,這組 API 就非常必要了。
(1)IIFE 寫法
(function ($) {
// 組件邏輯
})(jQuery);
第一次看到這種寫法容易困惑,拆開就懂了:
var fn = function ($) {
// 組件邏輯
};
fn(jQuery);
也就是先定義一個函式、立刻呼叫它,並把 jQuery 當實參傳進去。這麼做的好處是函式內部的 $ 保證是 jQuery,不必擔心與其他函式庫的 $ 衝突。
(2)掛到 jQuery 原型上
$.fn.combobox = function (options, param) {};
這是把自訂方法掛到 jQuery 物件上,之後就能寫成 $("#id").MyJsControl({}) 的形式。$.fn 就是 jQuery.prototype 的別名。
(3)合併參數
options = $.extend({}, $.fn.combobox.defaults, options || {});
這裡傳入空物件作為目標,意思是「不要污染 defaults 本身」,只把 defaults 與使用者參數合併成一個新物件。options || {} 則是防止使用者完全沒傳參時發生錯誤。
(4)預設參數列表
$.fn.combobox.defaults = {
url: null, param: null, data: null,
valueField: 'value', textField: 'text', placeholder: '請選擇',
onBeforeLoad: function (param) {},
onLoadSuccess: function () {},
onChange: function (value) {}
};
使用者沒傳的項目就落在這裡。如果你翻過其他 Bootstrap 組件的原始碼,會發現幾乎每個都有這麼一個 defaults——這是 jQuery 生態的慣例。
舉兩個例子:
bootstrap 上傳組件

bootstrap table 組件


看出規律了嗎?「IIFE 包裝 + 掛 $.fn + defaults 合併 + 字串分派方法 + 回呼鉤子」,這五件事就是 jQuery 組件的標準骨架。掌握它,自己封一個並不難。