DIV CSS 佈局教程網

jQuery 全域 AJAX 事件全解:ajaxStart、ajaxStop、ajaxSuccess 到 ajaxError
編輯:JQuery特效代碼     

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。

後者是常被忽略的技巧。若某個面板有自己的 loading 動畫,把 ajaxStart/ajaxStop 綁在該面板元素上,就能讓不同區域各自獨立顯示狀態,互不干擾。

實務應用:全域 loading 遮罩

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 範例裡很常見,複製前值得多看一眼。

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