瀏覽器原生的 alert 與 confirm 實在不好看,而且標準 API 並沒有提供「以對話框形式顯示自訂 HTML」的能力,所以多數專案都會自己封裝一套對話框元件。本文分享在專案中基於 Bootstrap 的 Modal 元件,封裝出 Alert、Confirm 與通用 Modal 的做法。三個元件加起來只有兩百多行,邏輯並不複雜。
完整程式碼可從文末連結下載,這裡先看效果。

原始碼裡附了一個 demo,模擬一個貼近真實需求的場景:
(1)點擊頁面按鈕,開啟一個預先定義好的 Modal:

(2)在 Modal 內填表並按下確定,觸發一系列表單校驗:
沒填 email 時:

填了 email 之後:

這兩個提示其實是為了示範 Alert 與 Confirm 的效果硬塞進去的,真實專案裡未必會有這麼彆扭的流程。
(3)注意 Password 為空時那個「確定」按鈕是禁用狀態。這個設計的用意是:確定按鈕最終要執行的是非同步任務,在任務成功回覆之前,不希望 Modal 被關掉,也不希望使用者重複點擊。
(4)用 setTimeout 模擬一個 3 秒後才回呼的非同步任務:
email 輸入 admin@admin 時提示提交成功,按下確定後關閉所有彈框:

輸入其他值時提示提交失敗,Modal 則留在原地:


元件定義中,註冊按鈕那一塊加了一些 AOP 風格的處理,並善用 jQuery 的延遲物件(Deferred)來完成非同步流程控制。細節請直接看原始碼。
寫一個好用的元件,最關鍵的一步往往不是敲鍵盤,而是先把原型長相與對外介面定下來。以下逐一說明。

呼叫時最多兩個參數:msg 傳入提示內容,onOk 處理確定鈕的回呼。支援兩種呼叫形式:
// 1. 沒有回呼
Alert('您選擇的訂單狀態不符合當前操作的條件,請刷新列表顯示最新數據後再繼續操作!');
// 2. 有回呼,改用 options 物件傳參
Alert({
msg: '您選擇的訂單狀態不符合當前操作的條件,請刷新列表顯示最新數據後再繼續操作!',
onOk: function () { }
});
不論有沒有 onOk,按下確定鈕都要關閉彈框。
原型與 Alert 只差一顆按鈕:

Confirm({
msg: '您選擇的訂單狀態不符合當前操作的條件,請確認是否要繼續操作!',
onOk: function () { },
onCancel: function () { }
});
onCancel 是點擊取消時的回呼,可以省略;同樣地,不論哪個回呼存在,按下按鈕都要關閉彈框。

var modal = new Modal({
title: '',
content: '',
width: 600,
buttons: [
{
html: '<button type="button" class="btn btn-sm btn-primary btn-ok">確定</button>',
selector: '.btn-ok',
callback: function () { /* 點擊確定的回呼 */ }
},
{
html: '<button type="button" class="btn btn-sm btn-default btn-cancel">取消</button>',
selector: '.btn-cancel',
callback: function () { /* 點擊取消的回呼 */ }
}
],
onContentReady: function () {
// Modal 掛進 DOM 且初始化完成時觸發,每個實例只會跑一次
},
onContentChange: function () {
// 呼叫 setContent 等類似方法改動內容時觸發
},
onModalShow: function () {
// 每次顯示 Modal 都會觸發
},
onModalHide: function () {
// 每次隱藏 Modal 都會觸發
}
});
$('#btn-audit').click(function () {
modal.open();
});
與 Alert/Confirm 不同,同一個頁面通常只需要一份 Alert 與 Confirm 實例,但可能需要多個 Modal,因此每個 Modal 都要各自 new。由於各 Modal 負責的事情不盡相同:
title:說明這個 Modal 正在處理什麼事情。content:Modal 的 HTML 內容。width:設定寬度,高度維持 auto。buttons:按鈕設定。一般兩個(確定/取消)就夠,但少數情況會需要更多,做成配置式比較有彈性。每顆按鈕三個參數:html 是結構,selector 方便用事件代理註冊回呼,callback 是點擊時的處理。onContentReady:適合在這裡初始化 Modal 內部的子元件,因為元件初始化通常只做一次。onContentChange:當一個 Modal 要服務不同場景、顯示不同內容時派上用場,但邏輯會稍微複雜些;若一個實例只辦一件事,這個回呼就用不到。onModalShow:使用情境很多,例如某個填表 Modal 每次開啟前都要 reset 表單,放在這裡處理最合適。onModalHide:算是預留介面,能想到的用法不多但偶爾很方便。理由也很實際:遮罩 Bootstrap 的 Modal 本身就支援;拖曳與縮放屬於錦上添花,對軟體本身價值有限,與其增加複雜度不如不做;Alert 與 Confirm 也不需要太多個人化,重點是統一風格、取代原生彈框的糟糕體驗。
var modal = new Modal({
title: '測試modal',
content: $('#modal-tpl').html(),
width: 500,
onOk: function () {
var $form = this.$modal.find('form');
var data = $form.serializeArray();
var postData = {};
data.forEach(function (obj) {
postData[obj.name] = obj.value;
});
if (!postData.email) {
Alert('請輸入EMAIL!');
return false; // 回傳 false,Modal 不關閉
}
var deferred = $.Deferred();
if (!postData.password) {
Confirm({
msg: 'Password為空,是否要繼續?',
onOk: function () { _post(); },
onCancel: function () { deferred.reject(); }
});
} else {
_post();
}
return $.when(deferred); // 回傳延遲物件,等它 resolve 才關閉 Modal
function _post() {
// 模擬非同步任務
setTimeout(function () {
if (postData.email === 'admin@admin') {
Alert({
msg: '提交成功!',
onOk: function () { deferred.resolve(); }
});
} else {
Alert({
msg: '提交失敗!',
onOk: function () { deferred.reject(); }
});
}
}, 3000);
}
},
onModalShow: function () {
var $form = this.$modal.find('form');
$form[0].reset(); // 每次開啟都重置表單
}
});
$('#btn-modal').click(function () {
modal.open();
});
初始化:$modal.modal();開啟:$modal.modal('show');關閉:$modal.modal('hide')。
事件方面,Bootstrap 絕大多數帶過渡效果的元件,事件都是成對出現的——一對是「現在進行時」,一對是「已完成」。Modal 定義了兩對:show.bs.modal / shown.bs.modal 與 hide.bs.modal / hidden.bs.modal,分別在開啟與關閉的過渡前後觸發。依我們的需求,要監聽 show.bs.modal 與 hidden.bs.modal,再各自派發自訂的 modalShow 與 modalHide。
選項部分:backdrop(是否顯示遮罩)、keyboard(是否支援鍵盤回呼)、show(初始化後是否立即顯示),三者預設都是 true,但在封裝時我們都設成 false:鍵盤回呼暫不考慮;初始化時當然不能立即彈出;backdrop 的原因見下一點。
一旦啟用 Bootstrap 的遮罩,會發現「點遮罩就會把彈框關掉」,這並不是我們想要的虛擬模態行為,所以必須把 backdrop 設為 false。但這樣又會連遮罩效果一起消失,於是只能自己寫一個簡易版:
var $body = $(document.body),
BackDrop = (function () {
var $backDrop,
count = 0,
create = function () {
$backDrop = $('<div class="modal-backdrop fade in"></div>').appendTo($body);
};
return {
show: function () {
!$backDrop && create();
$backDrop[0].style.display = 'block';
count++;
},
hide: function () {
count--;
if (!count) {
$backDrop.remove();
$backDrop = undefined;
}
}
};
})();
這裡之所以需要 count,是因為 BackDrop 是一個全域單例:同時開啟多個 Modal 時,每個 open() 都會呼叫 show()。只有計數歸零、代表所有 Modal 都關完了,才真正把遮罩移除,否則會出現「關掉一個,遮罩也跟著消失」的 bug。
ModalDialog.defaults = {
title: '',
content: '',
width: 600,
buttons: [
{
html: '<button type="button" class="btn btn-sm btn-primary btn-ok">確定</button>',
selector: '.btn-ok',
callback: getDefaultBtnCallbackProxy('onOk')
},
{
html: '<button type="button" class="btn btn-sm btn-default btn-cancel">取消</button>',
selector: '.btn-cancel',
callback: getDefaultBtnCallbackProxy('onCancel')
}
],
onOk: $.noop,
onCancel: $.noop,
onContentReady: $.noop,
onContentChange: $.noop, // content 替換之後的回呼
onModalShow: $.noop,
onModalHide: $.noop // modal 關閉之後的回呼
};
透過 buttons 配置好確定與取消兩顆預設按鈕,再為了簡化這兩顆按鈕的回呼設定,把介面往上提一層:onOk 與 onCancel 會在點擊對應按鈕時被呼叫。這兩個是純函式回呼,而 onContentReady 那種屬於事件回呼,性質不同。getDefaultBtnCallbackProxy 就是輔助註冊的橋樑:
var getDefaultBtnCallbackProxy = function (callbackName) {
return function () {
var opts = this.options,
callback = opts[callbackName] && typeof opts[callbackName] === 'function' ? opts[callbackName] : '';
return callback && callback.apply(this, arguments);
};
};
其中的 this 會被綁定到 Modal 實例上。
function ModalDialog(options) {
this.options = this.getOptions(options);
this.$modal = undefined;
this.$modalTitle = undefined;
this.$modalBody = undefined;
this.$modalFooter = undefined;
this.state = undefined;
}
主要是宣告會用到的實例變數。
open: function (state) {
this.state = state;
!this.$modal && initModal(this, this.options); // 延遲初始化
BackDrop.show();
this.$modal.modal('show');
}
這是原型方法,元件的初始化正是在這裡(首次呼叫時)才執行,也就是所謂的延遲初始化。
initModal = function (that, opts) {
var $modal = createModal(that);
that.setTitle(opts.title); // 原型方法:設定標題
that.setContent(opts.content); // 原型方法:設定 HTML 內容
that.addButtons(opts.buttons); // 原型方法:註冊按鈕
that.setWidth(opts.width); // 原型方法:設定寬度
bindHandler(that, opts); // 內部函式:註冊事件
$modal.modal(); // 初始化 Bootstrap 的 Modal 元件
$modal.trigger('contentReady'); // 觸發自訂的 contentReady 事件
}
bindHandler 的原始碼:
bindHandler = function (that, opts) {
var $modal = that.$modal;
typeof opts.onContentChange === 'function' &&
$modal.on('contentChange', $.proxy(opts.onContentChange, that));
typeof opts.onContentReady === 'function' &&
$modal.on('contentReady', $.proxy(opts.onContentReady, that));
typeof opts.onModalShow === 'function' &&
$modal.on('modalShow', $.proxy(opts.onModalShow, that));
typeof opts.onModalHide === 'function' &&
$modal.on('modalHide', $.proxy(opts.onModalHide, that));
// 把 Bootstrap 的事件包裝成自訂事件
$modal.on('show.bs.modal', function () { $modal.trigger('modalShow'); });
$modal.on('hidden.bs.modal', function () { $modal.trigger('modalHide'); });
};
用 $.proxy 把這幾個回呼的 this 綁到當前的 Modal 實例,使用起來更直觀;最後兩個監聽則是把 Bootstrap 的事件轉譯成我們自己定義的事件。
addButtons 的原始碼:
addButtons: function (buttons) {
var buttons = !$.isArray(buttons) ? [] : buttons,
that = this,
htmlS = [];
buttons.forEach(function (btn) {
htmlS.push(btn.html);
btn.selector && that.$modal.on('click', btn.selector, $.proxy(function (e) {
var self = this,
$btn = $(e.currentTarget);
$btn[0].disabled = true; // 點擊後先禁用按鈕,防止重複提交
var callback = typeof btn.callback === 'function' ? btn.callback : '',
ret = callback && callback.apply(self, arguments);
if (ret === false) {
// 回傳 false:恢復按鈕,但不關閉 Modal(後續動作被攔下了)
$btn[0].disabled = false;
return;
}
if (typeof (ret) === 'object' && 'done' in ret && typeof ret['done'] === 'function') {
// 回傳延遲物件:等它完成才恢復按鈕,且只有 resolve 時才關閉 Modal
ret.done(function () {
that.hide();
}).always(function () {
$btn[0].disabled = false;
});
} else {
$btn[0].disabled = false;
that.hide();
}
}, that));
});
this.$modalFooter.prepend($(htmlS.join('')));
}
這段程式碼一次處理了三件事:按鈕防重複點擊、Modal 的自動關閉、以及非同步任務的等待。回呼的三種回傳值各有不同意義——false 代表攔下後續動作;延遲物件代表「等我完成再說」;其他情況則直接關閉。
看清一件事:Alert 與 Confirm 其實就是一種特殊(且固定樣式)的 Modal,而且兩者可以共用同一個 Modal 實例。理解這點,封裝就水到渠成:
var Alert, Confirm;
(function () {
var modal;
var Proxy = function (isAlert) {
return function () {
if (arguments.length != 1) return;
var msg = typeof arguments[0] === 'string' && arguments[0] || arguments[0].msg || '',
onOk = typeof arguments[0] === 'object' && typeof arguments[0].onOk === 'function' && arguments[0].onOk,
onCancel = typeof arguments[0] === 'object' && typeof arguments[0].onCancel === 'function' && arguments[0].onCancel,
width = typeof arguments[0] === 'object' && arguments[0].width || 400;
var _onModalShow = function () {
this.setWidth(width);
this.setContent(msg);
// Alert 只有一顆按鈕,所以把取消鈕藏起來
this[(isAlert ? 'hide' : 'show') + 'Button']('.btn-cancel');
};
var _onModalHide = function () {
this.setContent(''); // 關閉後清空內容
};
// 延遲初始化這個全域共用的 modal
if (!modal) {
modal = new Modal({
'title': '操作提示',
onModalShow: _onModalShow,
onModalHide: _onModalHide,
onContentReady: function () {
this.$modalBody.css({
'padding-top': '30px',
'padding-bottom': '30px'
});
}
});
} else {
// 已初始化過,則重新綁定事件回呼
var $modal = modal.$modal;
$modal.off('modalShow modalHide');
$modal.on('modalShow', $.proxy(_onModalShow, modal));
$modal.on('modalHide', $.proxy(_onModalHide, modal));
}
modal.setOptions({
onOk: onOk || $.noop,
onCancel: onCancel || $.noop
});
modal.open();
};
};
Alert = Proxy(true);
Confirm = Proxy();
})();
這段程式碼著重處理了三個細節:
onModalShow/onModalHide 屬於事件回呼,初始化時傳進 options 之後,無法靠改 options 來替換,必須重新註冊;而 onOk/onCancel 是函式回呼,只要改動 options 上的引用即可生效。width 參數,因為 Alert 與 Confirm 的內容長度差異大,需要能各自調整寬度。本文記錄的是自己在定義 JS 元件時累積的一些方法與實踐。程式碼偏多、可讀性未必討喜,但好在思路簡單,而且這三個元件已經在好幾個專案裡跑過,目前來看足以應付所有彈框需求,因此整理出來分享,希望對有需要的朋友帶來幫助。