優秀的插件 API 設計,參數系統是核心。從無參數的硬編碼,到靈活的配置對象、智能默認值、功能性回調,再到可全局定制的默認值體系——每一步都在為使用者減負、為擴展留白。
jQuery.fn.shadow = function() {
return this.each(function() {
var $el = $(this);
for (var i = 0; i < 5; i++) { // 硬編碼 5 層
$el.clone().css({
position: "absolute",
left: $el.offset().left + i,
top: $el.offset().top + i,
zIndex: -1,
opacity: 0.1
}).appendTo("body");
}
});
};
// 僅能:$("h1").shadow(); 完全不可配置
jQuery.fn.shadow = function(slices, opacity, zIndex) {
// 必須按順序傳參,想改 opacity 必須傳前兩個
// $("h1").shadow(10, 0.1, -1);
};
缺點: 參數順序固定、可讀性差(魔法數字)、新增參數破壞兼容、無法跳過中間參數。
jQuery.fn.shadow = function(opts) {
return this.each(function() {
var $el = $(this);
for (var i = 0; i < opts.slices; i++) {
$el.clone().css({
left: $el.offset().left + i,
top: $el.offset().top + i,
zIndex: opts.zIndex,
opacity: opts.opacity
}).appendTo("body");
}
});
};
// 調用:語義清晰、順序無關、可選參數
$("h1").shadow({
slices: 5,
opacity: 0.25,
zIndex: -1
});
jQuery.fn.shadow = function(options) {
// 1. 定義默認值(文檔化所有可配置項)
var defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1
};
// 2. 合併:用戶選項覆蓋默認值
// 關鍵:第一個參數傳 {} 空對象,避免汙染 defaults 原對象
var opts = $.extend({}, defaults, options);
return this.each(function() {
var $el = $(this);
for (var i = 0; i < opts.slices; i++) {
$el.clone().css({
left: $el.offset().left + i,
top: $el.offset().top + i,
zIndex: opts.zIndex,
opacity: opts.opacity
}).appendTo("body");
}
});
};
// 使用示例
$("h1").shadow(); // 全部默認
$("h1").shadow({ opacity: 0.05 }); // 僅覆蓋 opacity
$("h1").shadow({ slices: 10 }); // 僅覆蓋 slices
var defaults = {
animation: { duration: 300, easing: "linear" }
};
// 淺合併:用戶傳 { animation: { duration: 500 } } 會丟失 easing!
var opts = $.extend({}, defaults, options);
// 深度合併:傳 true 為第一個參數
var opts = $.extend(true, {}, defaults, options);
// 結果:{ animation: { duration: 500, easing: "linear" } }
jQuery.fn.shadow = function(options) {
var defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1,
// 回調:計算每層偏移,默認對角線
sliceOffset: function(index) { return { x: index, y: index }; }
};
var opts = $.extend({}, defaults, options);
return this.each(function() {
var $el = $(this);
for (var i = 0; i < opts.slices; i++) {
var offset = opts.sliceOffset(i); // 調用回調獲取動態值
$el.clone().css({
left: $el.offset().left + offset.x,
top: $el.offset().top + offset.y,
zIndex: opts.zIndex,
opacity: opts.opacity
}).appendTo("body");
}
});
};
// 自定義偏移:陰影向左上擴散
$("h1").shadow({
sliceOffset: function(i) { return { x: -i, y: -2*i }; }
});
(index, element, instance) 或上下文對象.call(element, ...) 讓 this 指向當前 DOMjQuery.fn.shadow = function(options) {
// 從插件函數屬性讀取默認值,合併用戶選項
var opts = $.extend({}, jQuery.fn.shadow.defaults, options);
// ... 使用 opts
};
// 定義默認值(掛載在插件函數上)
jQuery.fn.shadow.defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1,
sliceOffset: function(i) { return { x: i, y: i }; }
};
// 全局修改默認值(影響所有後續調用)
$.fn.shadow.defaults.opacity = 0.2;
$.fn.shadow.defaults.slices = 3;
// 單次調用仍可覆蓋
$("h1").shadow({ opacity: 0.05 });
$.fn.dialog.defaults.theme = "dark"$.fn.datepicker.defaults.lang = "zh-TW"(function($) {
"use strict";
var pluginName = "shadow";
var defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1,
sliceOffset: function(i) { return { x: i, y: i }; },
onComplete: null // 全部層創建完成回調
};
function Shadow(element, options) {
this.$element = $(element);
this.options = $.extend(true, {}, defaults, options); // 深度合併
this._defaults = defaults;
this._name = pluginName;
this.init();
}
Shadow.prototype.init = function() {
this.createShadows();
if ($.isFunction(this.options.onComplete)) {
this.options.onComplete.call(this.$element[0], this);
}
};
Shadow.prototype.createShadows = function() {
var $el = this.$element;
var opts = this.options;
var shadows = [];
for (var i = 0; i < opts.slices; i++) {
var offset = opts.sliceOffset(i);
var $shadow = $el.clone().css({
position: "absolute",
left: $el.offset().left + offset.x,
top: $el.offset().top + offset.y,
margin: 0,
zIndex: opts.zIndex,
opacity: opts.opacity
}).appendTo("body");
shadows.push($shadow);
}
this.$shadows = shadows;
};
Shadow.prototype.destroy = function() {
this.$shadows.forEach(function($s) { $s.remove(); });
this.$element.removeData(pluginName);
};
// 插件入口
$.fn[pluginName] = function(options) {
var args = Array.prototype.slice.call(arguments, 1);
return this.each(function() {
var $this = $(this);
var instance = $this.data(pluginName);
if (!instance) {
$this.data(pluginName, new Shadow(this, options));
} else if (typeof options === "string") {
// 方法調用:$("h1").shadow("destroy")
if ($.isFunction(instance[options])) {
instance[options].apply(instance, args);
}
}
});
};
// 暴露默認值
$.fn[pluginName].defaults = defaults;
})(jQuery);
| 檢查項 | 標準 |
|---|---|
| 是否使用配置對象而非位置參數 | ✅ 必須 |
| 是否定義完整 defaults 並文檔化 | ✅ 必須 |
| $.extend 是否用 {} 保護 defaults | ✅ 必須 |
| 巢狀對象是否使用深度合併 | 視複雜度而定 |
| 回調函數參數/返回值/this 是否文檔化 | ✅ 必須 |
| 是否暴露 $.fn.plugin.defaults 允許全局配置 | 推薦 |
| 是否支持實例方法調用(字符串參數) | 推薦 |
| 是否提供 destroy/清理方法 | ✅ 必須 |
jQuery 插件參數設計的精髓在於 $.extend({}, defaults, options) 這一行。它實現了:默認值文檔化、用戶選項可選覆蓋、原默認值對象不被汙染、支持深度合併。在此基礎上引入回調函數實現行為擴展,掛載 .defaults 實現全局配置共享,構成了專業級插件參數系統的完整鏈路。記住:好的 API 設計是讓簡單的事情簡單,複雜的事情成為可能。