AJAX 是一套與伺服器交換資料的技術,能在不補送整頁的情況下更新網頁的一部分。以下把 $.ajax() 的常用參數逐一整理,方便查閱。
1. url
字串,送出請求的位址,預設為當前頁網址。
2. type
字串,請求方式,post 或 get,預設為 get。其他 HTTP 方法如 put、delete 也可用,但僅部分瀏覽器支援。
3. timeout
數字,請求逾時時間(毫秒)。此設定會覆蓋 $.ajaxSetup() 的全域設定。
4. async
布林,預設 true 表示非同步。設為 false 即為同步請求,但要注意同步會鎖住瀏覽器,使用者的其他操作必須等請求結束才能執行。
5. cache
布林,預設 true(dataType 為 script 時預設 false)。設為 false 將不會從瀏覽器快取載入請求資訊。
6. data
物件或字串,要送到伺服器的資料。若已是字串則原樣送出,否則會自動轉為字串;GET 請求會附加在網址之後。物件須為 key/value 格式,例如 {foo1:"bar1",foo2:"bar2"} 轉為 &foo1=bar1&foo2=bar2。若值為陣列,jQuery 會自動用相同名稱對應多個值,例如 {foo:["bar1","bar2"]} 轉為 &foo=bar1&foo=bar2。若想關掉自動轉換,可參考 processData。
7. dataType
字串,預期伺服器回傳的資料型別。不指定時,jQuery 會依 HTTP 封包的 mime 資訊自動判斷傳入 responseXML 或 responseText。可用值:
8. beforeSend
函數,送出請求前可修改 XMLHttpRequest 物件,例如加上自訂標頭;在此返回 false 可取消本次請求。唯一參數是 XHR 物件。
function (XMLHttpRequest) {
this; // 本次請求所傳入的 options 參數
}
9. complete
函數,請求完成後呼叫(成功或失敗皆會執行)。參數為 XHR 物件與描述請求類型的字串。
function (XMLHttpRequest, textStatus) {
this; // 本次請求所傳入的 options 參數
}
10. success
函數,請求成功後呼叫,兩個參數:一是伺服器回傳並依 dataType 處理後的資料,二是描述狀態的字串。
function (data, textStatus) {
// data 可能是 xmlDoc、jsonObj、html、text 等
this; // 本次請求所傳入的 options 參數
}
11. error
函數,請求失敗時呼叫,參數為 XHR 物件、錯誤資訊與捕捉到的錯誤物件(可選)。
function (XMLHttpRequest, textStatus, errorThrown) {
// 通常 textStatus 與 errorThrown 只有其中一個帶有資訊
this; // 本次請求所傳入的 options 參數
}
12. contentType
字串,送資訊到伺服器時的內容編碼型別,預設 "application/x-www-form-urlencoded",適合大多數場合。
13. dataFilter
函數,對 Ajax 回傳的原始資料做預處理,提供 data 與 type 兩個參數,回傳值會交由 jQuery 進一步處理。
function (data, type) {
return data; // 回傳處理後的資料
}
14. processData
布林,預設 true。預設會把資料轉為物件以配合 "application/x-www-form-urlencoded"。若要送出 DOM 樹或其他不希望被轉換的內容(例如 FormData),請設為 false。
15. scriptCharset
字串,僅在 dataType 為 "jsonp" 或 "script" 且 type 為 GET 時生效,用於強制修改字元集。通常在本機與遠端內容編碼不同時使用。
16. global
布林,預設 true,表示是否觸發全域 Ajax 事件。設為 false 則不觸發,ajaxStart 與 ajaxStop 等可用於控制各類事件。
17. ifModified
布林,預設 false。僅在伺服器資料有變動時才取新資料,判斷依據是 Last-Modified 標頭。
18. jsonp
字串,於 JSONP 請求中覆寫回呼函數名稱,用以取代網址參數中的 "callback" 部分。例如設為 'onJsonPLoad' 會把 "onJsonPLoad=?" 傳給伺服器。
19. username / 20. password
字串,分別用於回應 HTTP 存取認證請求的使用者名稱與密碼。
$(function () {
$('#send').click(function () {
$.ajax({
type: "GET",
url: "test.json",
data: {
username: $("#username").val(),
content: $("#content").val()
},
dataType: "json",
success: function (data) {
$('#resText').empty(); // 清空既有內容
var html = '';
$.each(data, function (commentIndex, comment) {
html += '<div class="comment">'
+ '<h6>' + comment['username'] + ':</h6>'
+ '<p class="para">' + comment['content'] + '</p>'
+ '</div>';
});
$('#resText').html(html);
}
});
});
});
實務上最常被忽略的兩個參數是 async 與 processData:前者決定頁面會不會在等待期間凍結,後者則直接影響 FormData 上傳能否成功。