寫 jQuery 外掛時,參數設計往往決定了這個外掛好不好用。本文以「文字陰影」效果為例,示範參數如何從無到有、從位置參數演進到物件映射、預設值與回呼函式,最後再加上自訂選擇符表達式。
jQuery.fn.shadow = function () {
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < 5; i++) {
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + i,
top: $originalElement.offset().top + i,
margin: 0,
zIndex: -1,
opacity: 0.1
})
.appendTo("body");
}
});
}
// 呼叫
$("h1").shadow();
原理是複製元素五份,每份向右下偏移一像素並降低不透明度,堆疊後就形成陰影。
jQuery.fn.shadow = function (slices, opacity, zIndex) {
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < slices; i++) {
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + i,
top: $originalElement.offset().top + i,
margin: 0,
zIndex: zIndex,
opacity: opacity
})
.appendTo("body");
}
});
}
// 呼叫
$("h1").shadow(10, 0.1, -1);
位置參數一多就容易搞混順序,改用物件傳入可讀性立刻提升。
jQuery.fn.shadow = function (opts) {
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < opts.slices; i++) {
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + i,
top: $originalElement.offset().top + i,
margin: 0,
zIndex: opts.zIndex,
opacity: opts.opacity
})
.appendTo("body");
}
});
}
// 呼叫
$("h1").shadow({
slices: 5,
opacity: 0.25,
zIndex: -1
});
jQuery.fn.shadow = function (options) {
var defaults = { slices: 5, opacity: 0.1, zIndex: -1 };
var opts = jQuery.extend(defaults, options); // options 中的值會覆蓋 defaults
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < opts.slices; i++) {
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + i,
top: $originalElement.offset().top + i,
margin: 0,
zIndex: opts.zIndex,
opacity: opts.opacity
})
.appendTo("body");
}
});
}
// 呼叫時只需傳要改的項目
$("h1").shadow({ opacity: 0.05 });
把偏移量抽成函式,呼叫端就能自訂陰影的方向與形狀。
jQuery.fn.shadow = function (options) {
var defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1,
sliceOffset: function (i) { return { x: i, y: i }; }
};
var opts = jQuery.extend(defaults, options);
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < opts.slices; i++) {
var offset = opts.sliceOffset(i); // 呼叫回呼函式
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + offset.x,
top: $originalElement.offset().top + offset.y,
margin: 0,
zIndex: opts.zIndex,
opacity: opts.opacity
})
.appendTo("body");
}
});
}
// 呼叫:陰影改往左上方延伸
$("h1").shadow({
sliceOffset: function (i) { return { x: -i, y: -2 * i }; }
});
把 defaults 掛在外掛的命名空間上,全域就能一次調整,不必改外掛原始碼。
jQuery.fn.shadow = function (options) {
// 以空物件作為 extend 的目標,避免污染 defaults 本身
var opts = jQuery.extend({}, jQuery.fn.shadow.defaults, options);
return this.each(function () {
var $originalElement = jQuery(this);
for (var i = 0; i < opts.slices; i++) {
var offset = opts.sliceOffset(i);
$originalElement.clone()
.css({
position: "absolute",
left: $originalElement.offset().left + offset.x,
top: $originalElement.offset().top + offset.y,
margin: 0,
zIndex: opts.zIndex,
opacity: opts.opacity
})
.appendTo("body");
}
});
}
jQuery.fn.shadow.defaults = {
slices: 5,
opacity: 0.1,
zIndex: -1,
sliceOffset: function (i) { return { x: i, y: i }; }
};
// 全域調整預設值
jQuery.fn.shadow.defaults.slices = 10;
$("h1").shadow({
sliceOffset: function (i) { return { x: -i, y: i }; }
});
這裡有個容易忽略的細節:jQuery.extend() 的第一個參數必須是空物件 {},而不是 defaults。因為一旦直接把 defaults 當成目標,每次呼叫都會就地修改它,而所有呼叫都共用同一份 defaults,全域預設值就會被最後一次呼叫的參數污染。
jQuery 允許擴充選擇符,讓型別判斷也能寫進 selector 裡。
/*
* 添加選擇符表達式
* element:當前 DOM 元素
* index:元素在結果集中的索引,對 :eq()、:lt() 這類選擇符有用
* matches:解析當前選擇符的正則結果陣列,matches[3] 是括號內的文字
* set:到目前為止匹配的元素集合
*/
jQuery.extend(jQuery.expr[':'], {
'css': function (element, index, matches, set) {
// matches[3] 例如 "width<100"
var parts = matches[3].split("");
var value = parseFloat(jQuery(element).css(parts[0]));
switch (parts[1]) {
case '<': return value < parseInt(parts[2]);
case '<=': return value <= parseInt(parts[2]);
case '=':
case '==': return value == parseInt(parts[2]);
case '>=': return value >= parseInt(parts[2]);
case '>': return value > parseInt(parts[2]);
}
}
});
呼叫方式:
<div style="width: 500px;">寬度 500</div>
<div style="width: 200px;">寬度 200</div>
<div style="width: 30px;">寬度 30</div>
<div style="width: 300px;">寬度 300</div>
<script>
$("div:css(width< 100)").addClass("heighlight");
</script>
只有寬度小於 100px 的那個 div 會被加上 class。
把這七個步驟串起來看,其實就是一套完整的演進路線:先寫死、再開放位置參數、接著改成物件映射、加上預設值與 extend 合併、用回呼函式開放客製行為、把預設值搬到命名空間讓全域可調,最後視需要擴充選擇符。其中「extend({}, defaults, options) 用空物件當目標」與「回傳 this 以支援連綴」是兩個最常被忽略、卻最影響外掛品質的細節。