DIV CSS 佈局教程網

擴充 easyui.datagrid:為本地載入資料補上遮罩提示
編輯:JQuery特效代碼     

EasyUI 的 datagrid 有兩種載入資料的方式:遠端(透過 url)與本地(透過 loadData)。差別在於——只有遠端載入時才會顯示「正在載入…」的遮罩層,載入完成後自動隱藏;本地載入則完全不顯示遮罩。這個取捨可以理解:本地資料已經在記憶體裡,通常快得不需要提示。

但實務上經常遇到另一種情況:專案沒有走 url 方式,而是用 loadData 塞入另一段非同步請求剛拿回來的資料。這時候從使用者按下按鈕到資料出現,中間可能有數百毫秒甚至數秒的空白,沒有任何回饋。此時遮罩提示就非常有必要了。

思路:抽出遠端載入的遮罩邏輯再對外開放

既然 EasyUI 內部已經有這套遮罩實作,最省事的做法就是把它從遠端流程裡抽出來,包成兩個可以隨時呼叫的方法。做法是透過 $.fn.datagrid.methods 擴充:

// jquery.datagrid 擴充
(function (){
    $.extend($.fn.datagrid.methods, {

        // 顯示遮罩
        loading: function(jq){
            return jq.each(function(){
                $(this).datagrid("getPager").pagination("loading");

                var opts = $(this).datagrid("options");
                var wrap = $.data(this, "datagrid").panel;

                if (opts.loadMsg) {
                    // 半透明遮罩鋪滿整個面板
                    $("<div class=\"datagrid-mask\"></div>")
                        .css({
                            display: "block",
                            width: wrap.width(),
                            height: wrap.height()
                        }).appendTo(wrap);

                    // 置中的提示文字
                    $("<div class=\"datagrid-mask-msg\"></div>")
                        .html(opts.loadMsg)
                        .appendTo(wrap)
                        .css({
                            display: "block",
                            left: (wrap.width()  - $("div.datagrid-mask-msg", wrap).outerWidth())  / 2,
                            top:  (wrap.height() - $("div.datagrid-mask-msg", wrap).outerHeight()) / 2
                        });
                }
            });
        },

        // 隱藏遮罩
        loaded: function(jq){
            return jq.each(function(){
                $(this).datagrid("getPager").pagination("loaded");
                var wrap = $.data(this, "datagrid").panel;
                wrap.find("div.datagrid-mask-msg").remove();
                wrap.find("div.datagrid-mask").remove();
            });
        }
    });
})(jQuery);

幾個實作細節值得說明。$.data(this, "datagrid").panel 是取得 datagrid 真正的容器元素,遮罩要掛在它上面才能正確覆蓋。pagination("loading") 與 pagination("loaded") 則是同步讓分頁列也進入載入狀態,視覺上才一致。提示文字用 opts.loadMsg 而非寫死,是為了尊重使用者在初始化時設定的訊息。置中算法用 (容器尺寸 - 提示框尺寸) / 2,是標準的手動置中。

使用方式

在呼叫 loadData 之前先開遮罩:

$("#dataGrid").datagrid("loadData", (function (){
    $("#dataGrid").datagrid("loading");     // 先顯示遮罩
    return [];                              // [] 處放入要載入的資料
})());

這個寫法巧妙地用了「立即執行的函式表達式」:函式在 loadData 的參數位置就被執行,因此 loading() 一定先跑,而函式的回傳值(資料陣列)才交給 loadData。

接著在 datagrid 的 onLoadSuccess 事件中關閉遮罩:

$("#dataGrid").datagrid({
    url: "...",
    onLoadSuccess: function (){
        $("#dataGrid").datagrid("loaded");
    }
});

onLoadSuccess 是關鍵——不論資料來自 url 或 loadData,只要渲染完成它就會觸發,所以遮罩一定能被關掉,不會永遠卡在畫面上。

更貼近真實場景的寫法

實務上資料多半來自另一次 ajax,而非同步就位。那麼與其用立即函式硬湊,不如把開關放在請求的前後:

function loadGrid(){
    var $grid = $("#dataGrid");
    $grid.datagrid("loading");               // 發請求前開遮罩

    $.ajax({
        url: "/api/orders",
        dataType: "json",
        success: function(rows){
            $grid.datagrid("loadData", rows);   // 資料就位,觸發 onLoadSuccess
        },
        error: function(){
            $grid.datagrid("loaded");           // 失敗時也要關掉,否則遮罩永遠不會消失
            $.messager.alert("提示", "資料載入失敗");
        },
        complete: function(){
            // 若已改用 onLoadSuccess 關閉,這裡可省略
        }
    });
}

務必注意的一點:只要呼叫了 loading(),就必須保證在所有路徑上都會呼叫 loaded()——包含成功、失敗、逾時三種情況。任何一條路徑漏掉,遮罩就會永久蓋住表格,使用者完全無法操作。把 loaded() 放在 complete 或 error 裡,是最保險的做法。

另外,遮罩只是一層 div,並不會阻止鍵盤操作。若表單操作嚴格,可考慮在 loading() 時同時加上 pointer-events 控制或 $.blockUI,並在 loaded() 還原。

writer:追夢客 20101030

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