jquery.blockUI.js 可將任意區塊鎖定並顯示載入中訊息,常用於 AJAX 請求期間防止重複提交、提升體驗。
/**
* 統一 AJAX 請求封裝
* @param {string} url - 請求網址
* @param {Function} onSuccess - 成功回呼
* @param {Object} params - 參數物件
* @param {string} method - 'GET' | 'POST'
* @param {boolean} isAsync - 是否非同步
* @param {boolean} isMask - 是否顯示遮罩
*/
function request(url, onSuccess, params = {}, method = 'POST', isAsync = true, isMask = true) {
const $mask = $('#div_mask'); // 頁面需有此容器:
$.ajax({
type: method,
url: url,
async: isAsync,
data: params,
dataType: 'json', // 視後端而定
beforeSend: function() {
if (isMask) {
$mask.block({
message: '<img src="/assets/loading.gif" alt="載入中...">',
css: {
border: 'none',
backgroundColor: 'transparent',
cursor: 'wait'
},
overlayCSS: {
backgroundColor: '#000',
opacity: 0.4
}
});
}
},
success: function(response) {
if (isMask) $mask.unblock();
onSuccess(response);
},
error: function(xhr, status, err) {
if (isMask) $mask.unblock();
console.error('AJAX 錯誤:', status, err);
// 可統一錯誤處理:alert、toast、導向錯誤頁
}
});
}
<!-- 頁面任意位置,建議 body 結尾 -->
<div id="div_mask" style="display:none;"></div>
$mask.block({
message: '<div class="spinner"></div><p>資料處理中,請稍候...</p>',
css: {
top: '40%',
left: '50%',
transform: 'translate(-50%, -50%)',
width: '200px',
textAlign: 'center',
color: '#fff',
border: 'none',
backgroundColor: 'rgba(0,0,0,0.7)',
padding: '20px',
borderRadius: '8px'
}
});
搭配 CSS 動畫:
.spinner {
width: 32px; height: 32px;
border: 3px solid #f3f3f3;
border-top: 3px solid #3498db;
border-radius: 50%;
animation: spin 1s linear infinite;
margin: 0 auto 12px;
}
@keyframes spin { to { transform: rotate(360deg); } }
// 僅鎖定特定表單或區塊
$('#myForm').block({ message: '驗證中...' });
// 完成後
$('#myForm').unblock();
| 問題 | 原因 | 解決 |
|---|---|---|
| 遮罩不消失 | error 或 complete 未呼叫 unblock() | 統一在 complete 回呼處理 |
| 多次點擊觸發多個遮罩 | 未在 beforeSend 禁用按鈕 | 按鈕 prop('disabled', true),complete 恢復 |
| z-index 被覆蓋 | 頁面其他元素 z-index 過高 | BlockUI 預設 z-index 1000,調整 $.blockUI.defaults.baseZ |
| 行動裝置遮罩無法滾動 | overflow: hidden 影響 | 設定 overlayCSS: { overflow: 'auto' } |
但若專案已使用 jQuery,BlockUI 仍是最快整合、API 最成熟的選擇。