這是 Wijmo 開源元件庫中的進度條 widget。它並非從零打造,而是繼承 jQuery UI 既有的 $.ui.progressbar,在其之上疊加標籤、動畫、多方向填充等能力。這種「繼承官方 widget 再擴充」的模式,是撰寫自家元件時非常值得參考的做法。
展示網站:https://wijmo.com/Wijmo-Open/samples/
必要依賴是 jQuery 1.4.2、jquery.ui.core.js 與 jquery.ui.widget.js。若要使用動畫效果,還需按需引入 jquery.effects.*.js 系列。HTML 只要一個帶尺寸的容器:
<div id="progressbar" style="width:***;height:***"></div>
<script>
$("#progressbar").wijprogressbar({ value: 60 });
</script>
| 選項 | 類型 | 預設 | 說明 |
|---|---|---|---|
| labelAlign | String | "center" | 標籤對齊位置,可用 east / west / center / north / south / running。running 會讓文字跟著進度移動。 |
| value | Number | 0 | 目前進度值 |
| minValue | Number | 0 | 最小值 |
| maxValue | Number | 100 | 最大值 |
| fillDirection | String | "east" | 填充方向:east / west / north / south |
| labelFormatString | String | "{1}%" | 標籤文字格式 |
| toolTipFormatString | String | "{1}%" | tooltip 文字格式 |
| indicatorIncrement | Number | 1 | 動畫時每次遞增的幅度,值越大動畫越「跳格」 |
| indicatorImage | String | "" | 進度條填充區的背景圖 |
| animationDelay | Number | 0 | 動畫啟動前的延遲毫秒數 |
| animationOptions | Options | {animated:'progress',duration:500} | 動畫參數,含 easing 與 duration |
格式字串是一組很有用的設計。{0} 或 {ProgressValue} 代表目前值、{1}/{PercentProgress} 代表百分比、{2}/{RemainingProgress} 代表剩餘量、{3}/{PercentageRemaining} 代表剩餘百分比、{4}/{Min} 與 {5}/{Max} 則是最小最大值。同時支援數字與名稱兩種寫法,是為了讓 template 更易讀。
widget 工廠約定,_create 在元件建立時呼叫一次。這裡先記下 min/max,加上 class,呼叫父類別的 _create,然後才建立自己的標籤節點:
_create: function () {
var self = this;
self.min = self.options.minValue;
self.max = self.options.maxValue;
self.element.addClass("ui-wijprogressbar");
$.ui.progressbar.prototype._create.apply(self, arguments); // 交給父類別
self.label = $("<span>")
.addClass("ui-progressbar-label ui-corner-left")
.appendTo(self.valueDiv);
self._initElements();
self._isInit = true;
self._refreshValue();
}
這段是整支程式最值得學的部分。不同選項變更後需要做的動作完全不同——數值類要重算百分比、樣式類要重建元素、格式化字串只要重繪文字。若一律無條件全量刷新,效能與正確性都會出問題:
_setOption: function (key, value) {
var val, self = this;
switch (key) {
case "value":
val = parseInt(value);
self.options[key] = val;
self._refreshValue(val);
break;
case "maxValue":
case "minValue":
val = parseInt(value);
self.options[key] = val;
self[key === "maxValue" ? "max" : "min"] = val;
self._refreshValue();
break;
case "labelFormatString":
case "toolTipFormatString":
self.options[key] = value;
self._refreshValue();
break;
case "orientation":
case "fillDirection":
case "labelAlign":
case "indicatorImage":
self.options[key] = value;
self._initElements(); // 需要重建元素
self._refreshValue();
break;
case "indicatorIncrement":
value = (value == 0 ? 1 : value); // 0 會造成除零,強制改為 1
self.options[key] = value;
self._initElements();
self._refreshValue();
break;
default: break;
}
$.Widget.prototype._setOption.apply(self, arguments);
}
最後一定要呼叫原型上的 _setOption,否則父類別的邏輯(例如 aria 屬性同步)會被跳過。
_refreshValue: function () {
var self = this;
if (!self._isInit) { return; } // 初始化未addon完成前不要跑
var value = self.value();
var percent = (value - self.min) / (self.max - self.min) * 100;
var o = self.options;
// 觸發可取消事件:回呼若傳回 true 就中止
var cancel = self._triggerEvent("beforeProgressChanging",
self.element.attr("aria-valuenow"), value, false);
if (cancel) { return; }
self.valueDiv.css({ width: "", height: "" });
if (o.animationOptions.animated && o.animationOptions.duration > 0) {
setTimeout($.proxy(function () {
var animations = $.ui.wijprogressbar.animations;
var easing = o.animationOptions.animated;
if (easing && !animations[easing]) { easing = "progress"; }
animations[easing]({
content: self.valueDiv,
complete: $.proxy(function () {
self._triggerEvent("progressChanged", ...);
}, self),
step: $.proxy(function (ovalue) { self._performAnimating(ovalue); }, self),
processValue: percent
}, o.animationOptions);
}, self), o.animationDelay);
} else {
self._refreshProgress(percent);
self._triggerEvent("progressChanged", ...);
}
}
這裡有兩個值得學的細節。$.proxy 用來綁定 this,避免 setTimeout 內的 this 指向 window。_triggerEvent 則是自製的可取消事件包裝,回呼若明確傳回 true,後續的進度更新就會被跳過——這是讓呼叫端能「拒絕一次進度變更」的關鍵設計。
文字跟著進度跑是最難處理的一種對齊。當進度條未滿時,標籤要貼在已填色的右端;滿了之後則要往內收,避免超出容器:
_performAnimating: function (obj) {
var self = this;
var len = Math.floor(obj / self.options.indicatorIncrement);
obj = len * self.options.indicatorIncrement; // 依 increment 取整
self._refreshProgress(obj);
if (self.options.labelAlign === "running") {
if (self._isHorizontal()) {
var eleWidth = self.element.width();
var labelWidth = self.label.outerWidth();
var progressWidth = self.valueDiv.outerWidth();
var left = eleWidth === progressWidth
? eleWidth - labelWidth
: obj * eleWidth / 100 - labelWidth
+ labelWidth * (eleWidth - progressWidth) / eleWidth;
self.label.css(self.options.fillDirection === "east" ? "left" : "right", left);
}
// 垂直方向同理,把 width 換成 height、left 換成 top
}
}
最後它把動畫抽成一個可覆寫的表,預設只提供一種 progress:
$.extend($.ui.wijprogressbar, {
animations: {
progress: function (options, additions) {
options = $.extend({ easing: "swing", duration: 1000 }, options, additions);
options.content.stop(true, true).animate({
widthvalue: options.processValue
}, options);
}
}
});
想自訂動畫,只要往 $.ui.wijprogressbar.animations 塞一個新方法,並把它的名稱設為 options.animated 即可,完全不必改動元件本體。
一、繼承而非重寫。能用 $.widget("ui.wijprogressbar", $.ui.progressbar, {...}) 繼承時就不要從零開始,父類別處理的邊界情況(ARIA、disabled 狀態、DOM 生命週期)往往比想像中多。
二、widget 只該管 UI 層。它負責呈現與事件,不該管資料從哪來。實用與否,用了才知道;而既然對外開放原始碼,功能就可以在使用者回饋後逐步補齊。
三、換膚交給 CSS Framework。所有 class 都採用 ui-widget、ui-corner-* 這套 jQuery UI 的語意化命名,因此搭配 ThemeRoller 就能輕鬆替換整組配色,不必動一行 JS。