DIV CSS 佈局教程網

動手做一個 jQuery 進度條 Widget:wijprogressbar 原始碼導讀
編輯:JQuery特效代碼     

這是 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>

可設定的 options

選項類型預設說明
labelAlignString"center"標籤對齊位置,可用 east / west / center / north / south / running。running 會讓文字跟著進度移動。
valueNumber0目前進度值
minValueNumber0最小值
maxValueNumber100最大值
fillDirectionString"east"填充方向:east / west / north / south
labelFormatStringString"{1}%"標籤文字格式
toolTipFormatStringString"{1}%"tooltip 文字格式
indicatorIncrementNumber1動畫時每次遞增的幅度,值越大動畫越「跳格」
indicatorImageString""進度條填充區的背景圖
animationDelayNumber0動畫啟動前的延遲毫秒數
animationOptionsOptions{animated:'progress',duration:500}動畫參數,含 easing 與 duration

格式字串是一組很有用的設計。{0} 或 {ProgressValue} 代表目前值、{1}/{PercentProgress} 代表百分比、{2}/{RemainingProgress} 代表剩餘量、{3}/{PercentageRemaining} 代表剩餘百分比、{4}/{Min} 與 {5}/{Max} 則是最小最大值。同時支援數字與名稱兩種寫法,是為了讓 template 更易讀。

_create:初始化的起點

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:設定變更時的處理

這段是整支程式最值得學的部分。不同選項變更後需要做的動作完全不同——數值類要重算百分比、樣式類要重建元素、格式化字串只要重繪文字。若一律無條件全量刷新,效能與正確性都會出問題:

_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:百分比計算與動畫分流

_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,後續的進度更新就會被跳過——這是讓呼叫端能「拒絕一次進度變更」的關鍵設計。

labelAlign 為 running 時的定位計算

文字跟著進度跑是最難處理的一種對齊。當進度條未滿時,標籤要貼在已填色的右端;滿了之後則要往內收,避免超出容器:

_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。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved