DIV CSS 佈局教程網

jQuery $.ajax() 參數完整解析:從常用選項到進階 callbacks
編輯:JQuery入門技巧     

$.ajax() 是 jQuery 與後端溝通的核心,參數雖多,但真正需要深究的其實集中在幾個。以下依重要度整理,並附基本範例與一個較完整的應用。

基本範例

$.ajax({
    url: 'test.do',
    data: { id: 123, name: 'xiaoming' },
    type: 'post',
    dataType: 'json',
    success: function(data) {
        alert(data);
        // TODO 處理回應
    },
    error: function(data) {
        alert(data);
        // TODO 錯誤處理
    }
});

請求設定

  • url(String):請求位址,預設為當前頁網址。
  • type(String):請求方法,post 或 get,預設 get。put、delete 等方法也可使用,但僅部分瀏覽器支援。
  • timeout(Number):請求逾時毫秒數,會覆蓋 $.ajaxSetup() 的全域設定。長時間查詢建議一定要設,否則使用者只會看到轉圈圈。
  • async(Boolean):預設 true(非同步)。設為 false 會鎖住瀏覽器,其他操作必須等請求完成,實務上應盡量避免。
  • cache(Boolean):預設 true(dataType 為 script 時預設 false)。設為 false 可停用瀏覽器快取,避免抓到舊資料。
  • data(Object/String):送往伺服器的資料。非字串會自動轉為字串字格式,get 請求會附加在 url 後。物件須為 key/value 形式,例如 {foo1:"bar1",foo2:"bar2"} 轉為 ?foo1=bar1&foo2=bar2;陣列則會產生同名的多筆,例如 {foo:["bar1","bar2"]} 轉為 ?foo=bar1&foo=bar2。
  • contentType(String):送出時的內容編碼類型,預設 application/x-www-form-urlencoded,適合大多數情況。要送 JSON 時改為 application/json。
  • processData(Boolean):預設 true,會把 data 轉為符合預設 content type 的字串。若要傳 DOM 樹或 FormData,須設為 false,並同時把 contentType 設為 false。
  • scriptCharset(String):僅在 dataType 為 jsonp 或 script 且 type 為 GET 時生效,用於強制指定字元集,常在本機與遠端編碼不同時使用。

dataType:預期回應的型別

若不指定,jQuery 會依 HTTP 回應的 MIME 自動判斷,再以 responseXML 或 responseText 傳給 callback。可選值:

  • xml:回傳 XML 文件,可用 jQuery 處理。
  • html:回傳純文字 HTML,其中的 script 標籤在插入 DOM 時會執行。
  • script:回傳純文字 JavaScript,結果預設不快取(除非明確開啟 cache)。跨網域請求時,所有 post 都會被轉為 get。
  • json:回傳 JSON 並解析為物件。
  • jsonp:JSONP 格式。使用 myurl?callback=? 時,jQuery 會自動把最後一個 ? 替換為產生的函式名以執行回呼。也可用 jsonp 參數自訂 callback 參數名。
  • text:回傳純文字字串。

callback 函式

beforeSend

送出前可修改 XMLHttpRequest 物件,例如加上自訂 HTTP 標頭;在此 return false 可取消本次請求。

beforeSend: function(XMLHttpRequest) {
    this;   // 本次 ajax 請求傳入的 options
}

complete

請求完成後(不論成功或失敗)都會呼叫,參數為 XMLHttpRequest 與描述狀態的字串。

complete: function(XMLHttpRequest, textStatus) {
    this;   // 本次請求的 options
}

success

成功時呼叫,兩個參數:經 dataType 處理後的資料,以及狀態字串。

success: function(data, textStatus) {
    // data 可能是 xmlDoc、jsonObj、html、text 等
    this;   // 本次請求的 options
}

error

失敗時呼叫,參數為 XMLHttpRequest、錯誤資訊、捕捉到的錯誤物件。

error: function(XMLHttpRequest, textStatus, errorThrown) {
    // 通常 textStatus 與 errorThrown 只有一個帶有資訊
    this;   // 本次請求的 options
}

其他設定

  • dataFilter(Function):對回傳的原始資料做前處理,參數為 data 與 type,回傳值再由 jQuery 進一步處理。
dataFilter: function(data, type) {
    return data;   // 處理後的資料
}
  • global(Boolean):預設 true,表示觸發全域 ajax 事件。設為 false 則不觸發,可用來讓單一請求跳過 ajaxStart / ajaxStop 之類的全域 loading 遮罩。
  • ifModified(Boolean):預設 false。僅在伺服器資料變動時才取新資料,判斷依據是 Last-Modified 標頭。
  • jsonp(String):在 jsonp 請求中覆寫 callback 函式名,例如 {jsonp:'onJsonPLoad'} 會把 onJsonPLoad=? 傳給伺服器。
  • username / password(String):回應 HTTP 存取認證時使用的帳號與密碼。

一個較完整的應用

$(function(){
    $('#send').click(function(){
        $.ajax({
            type: "GET",
            url: "test.json",
            data: {
                username: $("#username").val(),
                content:  $("#content").val()
            },
            dataType: "json",
            beforeSend: function(xhr) {
                xhr.setRequestHeader("Accept", "application/json");
            },
            success: function(data){
                $('#resText').empty();
                var html = '';
                $.each(data, function(commentIndex, comment){
                    html += '<div class="comment">'
                         +  '<span class="user">' + comment['username'] + '</span>'
                         +  '<p>' + comment['content'] + '</p>'
                         +  '</div>';
                });
                $('#resText').html(html);
            },
            error: function(xhr, textStatus, errorThrown){
                console.log(textStatus, errorThrown);
            },
            complete: function(){
                $('#send').removeAttr('disabled');
            }
        });
    });
});

幾點實務建議

  • 不要用 async: false 來「湊」同步流程,改用 Promise / $.when() 串接,畫面才不會凍住。
  • 回傳的 HTML 若以字串拼接後塞進頁面,記得對使用者輸入做轉义,避免 XSS。
  • 從 jQuery 3 起,success / error / complete 已標記為不建議使用,改用 .done() / .fail() / .always() 或 $.ajax().then(),風格上也更貼近標準 Promise。
  • 全域 loading 效果建議統一掛在 $(document).ajaxStart() / ajaxStop(),並對不需顯示 loading 的請求設 global: false。

以上就是 $.ajax() 的參數整理,希望對你的學習有所幫助。

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