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