jQuery 除了每個請求各自的 success/error 回呼之外,還提供了一整套全域 ajax 事件。這套機制的價值在於:不必替每一個 $.get、$.post 都重複寫一次 loading 與錯誤處理,只要在一個地方集中掛上監聽,全頁的請求狀態就都統一呈現。
| 事件 | 觸發時機 |
|---|---|
| ajaxStart | 第一個 ajax 請求開始時。僅在此刻觸發一次。 |
| ajaxSend | 每個請求實際送出前都會觸發,可讀取 settings 與 XHR 物件。 |
| ajaxSuccess | 請求成功完成時。 |
| ajaxError | 請求失敗時。 |
| ajaxComplete | 請求完成時,不論成功或失敗。 |
| ajaxStop | 所有進行中的請求都結束之後。同樣只觸發一次。 |
ajaxStart/ajaxStop 的「僅一次」特性特別重要:它是計數式的,五個並行請求時 ajaxStart 只跑一次、ajaxStop 要等到第五個都結束才跑。這正是全域 loading 遮罩需要的行為——否則遮罩會閃五次。
<html>
<head>
<title>jQuery Ajax - AjaxEvent</title>
<script src="jquery-1.4.3.js" type="text/javascript"></script>
<script type="text/javascript">
$(document).ready(function()
{
$("#btnAjax").bind("click", function(event)
{
$.get("Default.aspx", { resultType: "dddd" }, function(data){
$("#divResult").html(data);
});
});
// 請求開始(僅第一次觸發)
$("#divResult").ajaxStart(function(){
$(this).append('<div>ajax 開始執行</div><br />');
});
// 每個請求送出前
$("#divResult").ajaxSend(function(evt, request, settings){
$(this).append('<div>ajax 執行發送前</div><br />');
});
// 成功
$("#divResult").ajaxSuccess(function(evt, request, settings){
$(this).append('<div>ajax 執行成功</div><br />');
});
// 失敗
$("#divResult").ajaxError(function(evt, request, settings){
$(this).append('<div>ajax 執行發生錯誤</div><br />');
});
// 完成(成功或失敗都會觸發)
$("#divResult").ajaxComplete(function(evt, request, settings){
$(this).append('<div>ajax 執行完成</div><br />');
});
// 全部結束
$("#divResult").ajaxStop(function(){
$(this).append('<div>ajax 執行結束</div><br />');
});
});
</script>
</head>
<body>
<button id="btnAjax">發送 Ajax 請求</button><br/>
<div id="divResult"></div>
</body>
</html>
點一次按鈕,輸出順序會是:ajaxStart → ajaxSend → ajaxSuccess → ajaxComplete → ajaxStop。
範例中把事件綁在 #divResult 上而非 document,這其實有學問。全域 ajax 事件會沿 DOM 樹向上冒泡,因此綁在任何祖先元素上都能收到子孫元素發出的請求。實務上有兩種用法:
document 上——真正全域,攔截所有請求。後者是常被忽略的技巧。若某個面板有自己的 loading 動畫,把 ajaxStart/ajaxStop 綁在該面板元素上,就能讓不同區域各自獨立顯示狀態,互不干擾。
var pending = 0;
$(document)
.ajaxStart(function(){ $("#globalLoading").show(); })
.ajaxStop (function(){ $("#globalLoading").hide(); });
// 需要更精細控制時,自己數數量
$(document)
.ajaxSend(function(){ pending++; $("#globalLoading").show(); })
.ajaxComplete(function(){
pending--;
if (pending <= 0) { $("#globalLoading").hide(); }
});
ajaxError 也很適合集中處理 session 逾時——判斷回應狀態碼後直接導向登入頁,不必在每個請求的 error 裡重複寫:
$(document).ajaxError(function(evt, xhr, settings){
if (xhr.status === 401) {
window.location.href = "/login?returnUrl=" + encodeURIComponent(location.href);
return;
}
if (xhr.status === 500) {
console.error("伺服器錯誤:" + settings.url);
}
});
一、jQuery 3 已移除這些事件。ajaxStart、ajaxStop 等對應的事件在 jQuery 3.0 中被標示為 deprecated 並在後續版本移除,取而代之的是 jQuery.ajaxSend / ajaxStart / ajaxStop / ajaxComplete / ajaxSuccess / ajaxError 這些全域函式,寫法為 $(document).ajaxSend(function(){...}) 改成 jQuery.ajaxSend(...)。若你在維護升級過的專案,這是最容易出錯的一處。
二、範例中的 $(this).html(Date) 是筆誤,應為 data 或 new Date(),依原意判斷。這類小錯在 ajax 範例裡很常見,複製前值得多看一眼。