jQuery.ajax()

jQuery.ajax( url [, settings ] )

• url
  類型: String
  一個用來包含發送請求的URL字符串。
• settings
  類型: PlainObject
  一個以"{鍵:值}"組成的AJAX 請求設置。所有選項都是可選的。可以使用 $.ajaxSetup()設置任何默認參數。看 jQuery.ajax( settings )下所有設置的完整列表。

• 添加的版本: 1.0jQuery.ajax( [settings ] )

  • settings
    類型: PlainObject
    一個以"{鍵:值}"組成的AJAX 請求設置。所有選項都是可選的。可以使用 $.ajaxSetup()設置任何默認參數。
    • accepts (默認: 取決於數據類型)
      類型: PlainObject
      一個鍵/值對集合映射給定的 dataType 到其的MIME類型，它可以從發送 Accept請求頭信息中獲得。 請求頭信息通知服務器該請求需要接收何種類型的返回結果。 例如，下面定義一個自定義類型的 mycustomtype與請求一起發送：

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

      $.ajax({ accepts: { mycustomtype: 'application/x-some-custom-type' },   // Instructions for how to deserialize a `mycustomtype` converters: { 'text mycustomtype': function(result) { // Do Stuff return newresult; } },   // Expect a `mycustomtype` back from server dataType: 'mycustomtype' });

      注意: 對於這種類型，為了使其正常工作，您將需要在 converters中指定補充項。
    • async (默認: true)
      類型: Boolean
      默認設置下，所有請求均為異步請求（也就是說這是默認設置為 true ）。如果需要發送同步請求，請將此選項設置為 false 。跨域請求和 dataType: "jsonp" 請求不支持同步操作。注意，同步請求將鎖住瀏覽器，用戶其它操作必須等待請求完成才可以執行。 從 jQuery 1.8 開始, jqXHR ( $.Deferred)中使用 async: false 已經過時。您必須使用的 success/error/complete 的回調選項代替相應的jqXHR對象的方法，比如 jqXHR.done() 或者過時的jqXHR.success()。
    • beforeSend
      類型: Function( jqXHR jqXHR, PlainObject settings )
      請求發送前的回調函數，用來修改請求發送前jqXHR（在jQuery 1.4.x的中，XMLHttpRequest）對象，此功能用來設置自定義 HTTP 頭信息，等等。該jqXHR和設置對象作為參數傳遞。這是一個 Ajax事件 。在 beforeSend函數中返回 false將取消這個請求。 從jQuery 1.5開始， beforeSend選項將被訪問，不管請求的類型。
    • cache (默認: true, dataType為"script"和"jsonp"時默認為false)
      類型: Boolean
      如果設置為 false ，瀏覽器將不緩存此頁面。 注意: 設置 cache為 false將在 HEAD和GET請求中正常工作。它的工作原理是在GET請求參數中附加"_={timestamp}"（譯者注：時間戳）。該參數不是其他請求所必須的，除了在IE8中，當一個POST請求一個已經用GET請求過的URL。
    • complete
      類型: Function( jqXHR jqXHR, String textStatus )
      請求完成后回調函數 (請求 success 和 error之后均調用)。這個回調函數得到2個參數： jqXHR (在 jQuery 1.4.x中是 XMLHTTPRequest) 對象和一個描述請求狀態的字符串( "success", "notmodified", "nocontent"， "error", "timeout", "abort", 或者 "parsererror") 。 從jQuery 1.5開始， complete設置可以接受一個函數的數組。每個函數將被依次調用。這是一個 Ajax事件 。
    • contents
      類型: PlainObject
      一個以"{字符串/正則表達式}"配對的對象，根據給定的內容類型，解析請求的返回結果。 (1.5新增)
    • contentType (default: 'application/x-www-form-urlencoded; charset=UTF-8')
      Type: Boolean or String
      當將數據發送到服務器時，使用該內容類型。默認值是"application/x-www-form-urlencoded; charset=UTF-8"，適合大多數情況。如果你明確地傳遞了一個內容類型（Content-Type）給 $.ajax()，那么他總是會發送給服務器（即使沒有數據要發送）。從 jQuery 1.6 開始，你可以傳遞 false來告訴jQuery，沒有設置任何內容類型頭信息。 注意：W3C的XMLHttpRequest的規范規定，數據將總是使用UTF-8字符集傳遞給服務器；指定其他字符集無法強制瀏覽器更改編碼。 注意:對於跨域請求，內容類型設置為 application/x-www-form-urlencoded, multipart/form-data, 或 text/plain以外， 將觸發瀏覽器發送一個預檢OPTIONS請求到服務器。
    • context
      類型: Object
      這個對象用於設置Ajax相關回調函數的上下文。 默認情況下，這個上下文是一個ajax請求使用的參數設置對象，（ $.ajaxSettings合並獨傲這個設置，傳遞給 $.ajax）。比如指定一個DOM元素作為context參數，這樣就設置了 complete回調函數的上下文為這個DOM元素。就像這樣：

      1 2 3 4 5 6

      $.ajax({ url: "test.html", context: document.body }).done(function() { $(this).addClass("done"); });

    • converters (默認: {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})
      類型: PlainObject
      一個數據類型到數據類型轉換器的對象。每個轉換器的值是一個函數，返回經轉換后的請求結果。 ( 1.5新增)
    • crossDomain (默認: 同域請求為false， 跨域請求為true)
      類型: Boolean
      如果你想在同一域中強制跨域請求（如JSONP形式），例如，想服務器端重定向到另一個域，那么需要將crossDomain設置為 true 。 ( 1.5 新增)
    • data
      類型: PlainObject 或 String 或 Array
      發送到服務器的數據。將自動轉換為請求字符串格式。GET 請求中將附加在 URL 后面。查看 processData 選項說明，以禁止此自動轉換。對象必須為"{鍵:值}"格式。如果這個參數是一個數組，jQuery會按照 traditional 參數的值， 將自動轉化為一個同名的多值查詢字符串(查看下面的說明)。愚人碼頭注：如 {foo:["bar1", "bar2"]} 轉換為 '&foo=bar1&foo=bar2'。
    • dataFilter
      類型: Function( String data, String type ) => Anything
      一個函數被用來處理XMLHttpRequest的原始響應數據。這是一個預過濾功能，凈化響應。您應該返回安全數據。提供data和type兩個參 數：data是Ajax返回的原始數據，type是調用jQuery.ajax時提供的dataType參數。
    • dataType (default: Intelligent Guess (xml, json, script, or html))
      Type: String
      從服務器返回你期望的數據類型。 如果沒有指定，jQuery將嘗試通過MIME類型的響應信息來智能判斷（一個XML MIME類型就被識別為XML，在1.4中 JSON將生成一個JavaScript對象，在1.4中 script 將執行該腳本，其他任何類型會返回一個字符串）。 可用的類型（以及結果作為第一個參數傳遞給成功回調函數）有：

      • "xml": 返回 XML 文檔，可以通過 jQuery 處理。
      • "html": 返回純文本 HTML 文本；包含的script標簽會在插入DOM時執行。
      • "script": 把響應的結果當作 JavaScript 執行，並將其當作純文本返回。默認情況下會通過在URL中附加查詢字符串變量 ，_=[TIMESTAMP]， 禁用緩存結果，除非設置了cache參數為true。注意: 在遠程請求時(不在同一個域下)，所有POST請求都將轉為GET請求。(愚人碼頭注：因為將使用DOM的script標簽來加載)
      • "json":把響應的結果當作 JSON 執行，並返回一個JavaScript對象。跨域"json" 請求轉換為"jsonp"，除非該請求在其請求選項中設置了jsonp:false。JSON 數據以嚴格的方式解析; 任何畸形的JSON將被拒絕，並且拋出解析錯誤信息。在jQuery1.9中，一個空響應也將被拒絕;服務器應該返回null或 {}響應代替。（見json.org的更多信息，正確的JSON格式。）
      • "jsonp": 以 JSONP 的方式載入 JSON 數據塊。會自動在所請求的URL最后添加"?callback=?"。默認情況下會通過在URL中附加查詢字符串變量 ，_=[TIMESTAMP]， 禁用緩存結果，除非設置了cache參數為true。
      • "text": 返回純文本字符串。
      • 多個用空格分割的值:從 jQuery 1.5 開始， jQuery可以內容類型（Content-Type）頭收到並轉換一個您需要的數據類型。例如，如果你想要一個文本響應為XML處理，使用"text xml"數據類型。您也可以將一個JSONP的請求，以文本形式接受，並用jQuery以XML解析: "jsonp text xml"。同樣地可以使用"jsonp xml"簡寫,首先會嘗試從 jsonp 到 xml 的轉換，如果轉換失敗，就先將 jsonp 轉換成 text, 然后再由 text 轉換成 xml。
    • error
      類型: Function( jqXHR jqXHR, String textStatus, String errorThrown )
      請求失敗時調用此函數。有以下三個參數：jqXHR (在 jQuery 1.4.x前為XMLHttpRequest) 對象、描述發生錯誤類型的一個字符串 和 捕獲的異常對象。如果發生了錯誤，錯誤信息（第二個參數）除了得到 null之外，還可能是 "timeout", "error", "abort" ，和 "parsererror"。 當一個HTTP錯誤發生時， errorThrown 接收HTTP狀態的文本部分，比如： "Not Found"（沒有找到） 或者 "Internal Server Error."（服務器內部錯誤）。 從jQuery 1.5開始, 在 error設置可以接受函數組成的數組。每個函數將被依次調用。 注意： 此處理程序在跨域腳本和JSONP形式的請求時不被調用。這是一個 Ajax Event。
    • global (默認: true)
      類型: Boolean
      無論怎么樣這個請求將觸發全局AJAX事件處理程序。默認是 true 。設置為 false 將不會觸發全局 AJAX 事件，如 ajaxStart 或者 ajaxStop。這可以用來控制各種 Ajax Event.
    • headers (默認: {})
      類型: PlainObject
      一個額外的"{鍵:值}"對映射到請求一起發送。此設置會在 beforeSend 函數調用之前被設置 ;因此，請求頭中的設置值，會被 beforeSend 函數內的設置覆蓋 。 (1.5 新增 ）
    • ifModified (默認: false)
      類型: Boolean
      只有上次請求響應改變時，才允許請求成功。使用 HTTP 包 Last-Modified 頭信息判斷。默認值是 false，忽略HTTP頭信息。在jQuery 1.4中，他也會檢查服務器指定的'etag'來確定數據沒有被修改過。
    • isLocal (默認: 取決於當前的位置協議)
      類型: Boolean
      允許當前環境被認定為“本地”，（如文件系統），即使jQuery默認情況下不會這么做。以下協議目前公認為本地： file, *-extension, and widget。如果 isLocal設置需要修改，建議在 $.ajaxSetup()方法中這樣做一次。 (1.5 新增 ）
    • jsonp
      類型: String 或者 Boolean
      在一個JSONP請求中重寫回調函數的名字。這個值用來替代在"callback=?"這種GET或POST請求中URL參數里的"callback"部分，比如{jsonp:'onJsonPLoad'}會導致將"onJsonPLoad=?"傳給服務器。 在jQuery 1.5，，設置 jsonp選項為 false，阻止了jQuery從加入"?callback"字符串的URL或試圖使用"=?"轉換。在這種情況下，你也應該明確設置 jsonpCallback設置。例如, { jsonp: false, jsonpCallback: "callbackName" }。如果你不信任你的Ajax請求的目標，出於安全原因， 考慮 設置 jsonp 屬性為 false。
    • jsonpCallback
      類型: String, Function
      為jsonp請求指定一個回調函數名。這個值將用來取代jQuery自動生成的隨機函數名。這主要用來讓jQuery生成一個獨特的函數名，這樣管理請求更容易，也能方便地提供回調函數和錯誤處理。你也可以在想讓瀏覽器緩存GET請求的時候，指定這個回調函數名。 從jQuery 1.5開始，你也可以使用一個函數作為該參數設置，在這種情況下，該函數的返回值就是 jsonpCallback的結果。
    • method (default: 'GET')
      Type: String
      HTTP 請求方法 (比如： "POST", "GET ", "PUT")。 (添加版本: 1.9.0)。（愚人碼頭注：如果你使用jQuery 1.9.0 之前的版本，你需要使用type選項。）
    • mimeType
      類型: String
      一個mime類型用來覆蓋 XHR的 MIME類型。 (1.5 新增 ）
    • password
      類型: String
      用於響應HTTP訪問認證請求的密碼
    • processData (默認: true)
      類型: Boolean
      默認情況下，通過 data選項傳遞進來的數據，如果是一個對象(技術上講只要不是字符串)，都會處理轉化成一個查詢字符串，以配合默認內容類型 "application/x-www-form-urlencoded"。如果要發送 DOM 樹信息或其它不希望轉換的信息，請設置為 false。
    • scriptCharset
      類型: String
      僅適用於當"script"傳輸使用時（例如，跨域的"jsonp"或 dataType選項為"script" 和 "GET"類型）。請求中使用在script標簽上設置 charset 屬性。通常只在本地和遠程的內容編碼不同時使用。
    • statusCode (默認: {})
      類型: PlainObject

      一組數值的HTTP代碼和函數對象，當響應時調用了相應的代碼。例如，如果響應狀態是404，將觸發以下警報：

      1 2 3 4 5 6 7

      $.ajax({ statusCode: { 404: function() { alert("page not found"); } } });

      如果請求成功，狀態代碼對應的函數作為回調的成功相同的參數;如果在一個錯誤的結果，他們采取了相同的參數error回調。

      (1.5 新增 ）
    • success
      類型: Function( Object data, String textStatus, jqXHR jqXHR )
      請求成功后的回調函數。這個函數傳遞3個參數：從服務器返回的數據，並根據dataType參數進行處理后的數據，一個描述狀態的字符串;還有 jqXHR（在jQuery 1.4.x前為XMLHttpRequest） 對象 。 在jQuery 1.5， 成功設置可以接受一個函數數組。每個函數將被依次調用。這是一個 Ajax Event
    • success
      Type: Function( Anything data, String textStatus, jqXHR jqXHR )
      請求成功后的回調函數。這個函數傳遞3個參數：從服務器返回的數據，並根據dataType參數進行處理后的數據或 dataFilter回調函數，如果指定的話；一個描述狀態的字符串;還有 jqXHR（在jQuery 1.4.x前為XMLHttpRequest） 對象 。 在jQuery 1.5， 成功設置可以接受一個函數數組。每個函數將被依次調用。這是一個 Ajax Event
    • timeout
      類型: Number
      設置請求超時時間（毫秒）。此設置將覆蓋 $.ajaxSetup() 里的全局設置。 超時周期開始於 $.ajax 訪問成功的那個時間點；如果幾個其他請求都在進步並且瀏覽器有沒有可用的連接，它有可能在被發送前就超時了。 在 jQuery 1.4.x 和前面的版本中, 如果請求超時，XMLHttpRequest對象是處於無效狀態;訪問任何對象的成員可能會拋出一個異常。 只有在 Firefox 3.0+,script 和 JSONP請求在超時后不能被取消;該腳本將運行即使超時后到達。
    • traditional
      類型: Boolean
      如果你想要用傳統的方式來序列化數據，那么就設置為 true。請參考工具分類下面的 jQuery.param 方法.
    • type (默認: 'GET')
      類型: String
      method選項的別名。如果你使用jQuery 1.9.0 之前的版本，你需要使用 type選項。
    • url (默認: 當前頁面地址)
      類型: String
      發送請求的地址。
    • username
      類型: String
      於響應HTTP訪問認證請求的用戶名
    • xhr (默認: 當可用的ActiveXObject（IE）中，否則為XMLHttpRequest)
      類型: Function()
      回調創建XMLHttpRequest對象。當可用時默認為ActiveXObject（IE）中，否則為XMLHttpRequest。提供覆蓋你自己的執行的XMLHttpRequest或增強工廠。
    • xhrFields
      類型: PlainObject

      一對“文件名-文件值”組成的映射，用於設定原生的 XHR對象。例如，如果需要的話，在進行跨域請求時，你可以用它來設置withCredentials為true。

      1 2 3 4 5 6

      $.ajax({ url: a_cross_domain_url, xhrFields: { withCredentials: true } });

      在 jQuery 1.5中， withCredentials屬性不會傳遞給原生的XHR從而對於需要使用此屬性的 CORS 請求，則只能忽略這個屬性。。出於這個原因，我們建議您使用jQuery1.5.1+，如果您需要使用它。

      (1.5.1新增)

jQuery 發送的所有 Ajax 請求，內部都會通過調用 $.ajax() 函數來實現。通常沒有必要直接調用這個函數，可以使用幾個已經封裝的簡便方法，如$.get()和.load()。如果你需要用到那些不常見的選項，那么， $.ajax()使用起來更靈活。

在簡單地說， $.ajax()函數可以不帶參數調用：

1

$.ajax();

注意: 所有的選項都可以通過$.ajaxSetup() 函數來全局設置

這個例子中，不使用選項，加載當前頁面的內容，但其結果沒用的。若要使用結果，我們可以實現的回調功能之一。

jqXHR 對象

從jQuery 1.5開始，$.ajax() 返回XMLHttpRequest（jqXHR）對象，該對象是瀏覽器的原生的XMLHttpRequest對象的一個超集。例如，它包含responseText和responseXML屬性，以及一個getResponseHeader()方法。當傳輸機制不是是XMLHttpRequest時（例如，一個JSONP請求腳本，返回一個腳本 tag 時），jqXHR對象盡可能的模擬原生的XHR功能。

從jQuery 1.5.1開始， jqXHR對象還包含了overrideMimeType方法 (它在jQuery 1.4.x中是有效的，但是在jQuery 1.5中暫時的被移除)。.overrideMimeType() 方法可能用在beforeSend()的回調函數中，例如，修改響應的Content-Type信息頭：

1 2 3 4 5 6 7 8 9 10

$.ajax({ url: "http://fiddle.jshell.net/favicon.png", beforeSend: function ( xhr ) { xhr.overrideMimeType("text/plain; charset=x-user-defined"); } }).done(function ( data ) { if( console && console.log ) { console.log("Sample of data:", data.slice(0, 100)); } });

從 jQuery 1.5 開始，$.ajax()返回的jqXHR對象 實現了 Promise 接口, 使它擁有了 Promise 的所有屬性，方法和行為。（見Deferred object獲取更多信息）。為了讓回調函數的名字統一，便於在$.ajax()中使用。jqXHR也提供.error() .success()和.complete()方法。這些方法都帶有一個參數，該參數是一個函數，此函數在 $.ajax()請求結束時被調用,並且這個函數接收的參數，與調用 $.ajax()函數時的參數是一致。這將允許你在一次請求時，對多個回調函數進行賦值，甚至允許你在請求已經完成后，對回調函數進行賦值(如果該請求已經完成，則回調函數會被立刻調用)。

• jqXHR.done(function(data, textStatus, jqXHR) {});

  一個可供選擇的 success 回調選項的構造函數，.done()方法取代了的過時的jqXHR.success()方法。請參閱deferred.done()的實現細節。

• jqXHR.fail(function(jqXHR, textStatus, errorThrown) {});

  一種可供選擇的 error 回調選項的構造函數，.fail()方法取代了的過時的.error()方法。請參閱deferred.fail()的實現細節。

• jqXHR.always(function(data|jqXHR, textStatus, jqXHR|errorThrown) { });

  一種可供選擇的 complete 回調選項的構造函數，.always()方法取代了的過時的.complete()方法。

  在響應一個成功的請求后，該函數的參數和.done()的參數是相同的：data, textStatus, 和 jqXHR 對象.對於失敗的請求，參數和.fail()的參數是相同的：jqXHR 對象, textStatus, 和 errorThrown。請參閱deferred.always()的實現細節。

• jqXHR.then(function(data, textStatus, jqXHR) {}, function(jqXHR, textStatus, errorThrown) {});

  包含了 .done() 和 .fail()方法的功能，（從 jQuery 1.8 開始）允許底層被操縱。請參閱deferred.then()的實現細節。

推薦使用的注意事項: jqXHR.success(), jqXHR.error(), 和 jqXHR.complete()回調從 jQuery 1.8開始 被棄用過時。他們將最終被取消，您的代碼應做好准備， 從jQuery 3.0開始被刪除，你可以使用jqXHR.done(), jqXHR.fail(), 和 jqXHR.always() 代替。

1 2 3 4 5 6 7 8 9 10 11

// Assign handlers immediately after making the request, // and remember the jqxhr object for this request var jqxhr = $.ajax( "example.php" ) .done(function() { alert("success"); }) .fail(function() { alert("error"); }) .always(function() { alert("complete"); });   // perform other work here ...   // Set another completion function for the request above jqxhr.always(function() { alert("second complete"); });

this在所有的回調中的引用，是這個對象在傳遞給$.ajax的設置中上下文；如果沒有指定context（上下文），this 引用的是Ajax設置的本身。

為了向后兼容XMLHttpRequest ，一jqXHR對象將公開下列屬性和方法：

• readyState
• status
• statusText
• responseXML and/or responseText 當底層的請求分別作出XML和/或文本響應
• setRequestHeader(name, value) 從標准出發，通過替換舊的值為新的值，而不是替換的新值到舊值
• getAllResponseHeaders()
• getResponseHeader()
• abort()

假如沒有onreadystatechange屬性，因為不同的狀態可以分別在 success ， error ， complete和statusCode 方法中進行處理。

Callback Function Queues（回調函數）

beforeSend, error, dataFilter, success 和 complete接受的回調函數是在合適的時間調用。

從jQuery 1.5開始， fail ， done ，和從jQuery 1.6開始的always回調鈎子（hooks）采用先入先出隊列管理。這意味着你可以為每個掛鈎分配多個回調。見Deferred object methods ，這是實現內部的$.ajax()回調鈎子（hooks）。

這里有$.ajax()提供的回調鈎子 （hooks），如下：

1. beforeSend 在發送請求之前調用，它接收jqXHR對象和settings作為參數對象。
2. error 在請求出錯時調用。如果請求失敗，在它們的順序依次登記。他們接受jqXHR ，字符串表示的錯誤類型，以及異常對象（如果有的話）。一些內置的錯誤會將 "abort", "timeout", "No Transport" 等字符串作為異常對象。
3. dataFilter 在請求成功之后調用。傳入返回的數據以及dataType參數的值。並且必須返回新的數據（可能是處理過的）傳遞給success回調函數。
4. success 當請求成功並接收到返回數據之后調用。傳入返回后的數據，以及包含成功代碼的字符串和jqXHR對象。
5. Promise callbacks — .done(), .fail(), .always(), and .then() — 根據他們注冊的順序被調用。
6. complete 請求完成時，無論是在失敗或成功，它們按順序依次執行回調。他們收到jqXHR對象，以及一個包含成功或錯誤代碼。

Data Types（數據類型）

$.ajax()調用不同類型的響應，被傳遞到成功處理函數之前，會經過不同種類的預處理。 預處理的類型取決於由更加接近默認的Content-Type響應，但可以明確使用dataType選項進行設置。如果提供了dataType選項， 響應的Content-Type頭信息將被忽略。

有效的數據類型是text， html， xml， json，jsonp，和 script.

如果指定的是text 或 html， 則不會預處理。 這些數據被簡單地傳遞給成功處理函數， 並通過該jqXHR對象的responseText屬性獲得的。

如果指定的是xml， 響應結果作為XMLDocument，在傳遞給成功處理函數之前使用jQuery.parseXML進行解析。 XML文檔是可以通過該jqXHR對象的responseXML屬性獲得的。

如果指定的是json，響應結果作為一個對象，在傳遞給成功處理函數之前使用jQuery.parseJSON進行解析。 解析后的JSON對象可以通過該jqXHR對象的responseJSON屬性獲得的。

如果指定的是script ，$.ajax() 執行這段 JavaScript，這段 JavaScript 從服務器接收到，在傳遞給成功處理函數之前是一個字符串。

如果指定的是jsonp ，$.ajax()會自動在請求的URL后面增加一個查詢字符串參數 callback=?（默認） 。傳遞給$.ajax() 設置中的jsonp 和 jsonpCallback屬 性可以被用來指定， 分別為 查詢字符串參數的名稱和JSONP回調函數的名稱。服務器應返回有效的JavaScript，傳遞JSON響應到回調函數（愚人碼頭注：例 如，flightHandler({"code": "CA1998","price": 1780,"tickets": 5});等）。 在包含JSON對象的相應結果傳遞給成功處理函數之前，$.ajax() 將執行返回的JavaScript， 調用JSONP回調函數。

更多JSONP信息可以參閱詳細介紹了其使用的原帖.

Sending Data to the Server（發送數據到服務器）

默認情況下，Ajax請求使用GET方法。如果要使用POST方法，可以設定type參數值。這個選項也會影響 data 選項中的內容如何發送到服務器。POST數據將被發送到服務器使用UTF-8字符集，根據W3C XMLHttpRequest的標准。

data選項既可以包含一個查詢字符串，比如 key1=value1&key2=value2，也可以是一個映射，比如 {key1: 'value1', key2: 'value2'} 。如果使用了后者的形式，則數據再發送前會用jQuery.param() 將其轉換成查詢字符串。這個處理過程也可以通過設置processData選項為false來回避。如果我們希望發送一個XML對象給服務器時，這種處理可能並不合適。並且在這種情況下，我們也應當改變contentType 選項的值，用其他合適的MIME類型來取代默認的 application/x-www-form-urlencoded 。

Advanced Options（高級選項）

global選項用於阻止響應注冊的回調函數，比如.ajaxSend(), .ajaxError()，以及類似的方法。這在有些時候很有用，比如發送的請求非常頻繁且簡短的時候，就可以在.ajaxSend()里禁用這個。跨域腳本和JSONP請求，全局選項自動設置為false。更多關於這些方法的詳細信息，請參閱下面的內容。

如果服務器需要HTTP認證，可以使用用戶名和密碼可以通過 username 和 password 選項來設置。

Ajax請求是限時的，所以錯誤警告被捕獲並處理后，可以用來提升用戶體驗。請求超時這個參數通常就保留其默認值，要不就通過$.ajaxSetup()來全局設定，很少為特定的請求重新設置timeout選項。

默認情況下，請求總會被發出去，但瀏覽器有可能從他的緩存中調取數據。要禁止使用緩存的結果，可以設置cache參數為false。如果希望判斷數據自從上次請求后沒有更改過就報告出錯的話，可以設置ifModified為true。

scriptCharset允許給<script>標簽的請求設定一個特定的字符集，用於script 或者 jsonp類似的數據。當腳本和頁面字符集不同時，這特別好用。

Ajax的第一個字母是“asynchronous”的開頭字母，這意味着所有的操作都是並行的，完成的順序沒有前后關系。$.ajax()的async參數總是設置成true，這標志着在請求開始后，其他代碼依然能夠執行。強烈不建議把這個選項設置成false，這意味着所有的請求都不再是異步的了，這也會導致瀏覽器被鎖死。

$.ajax()函數返回他創建的XMLHttpRequest對象。通常jQuery只在內部處理並創建這個對象，但用戶也可以通過xhr 選項來傳遞一個自己創建的xhr對象。返回的對象通常已經被丟棄了，但依然提供一個底層接口來觀察和操控請求。比如說，調用對象上的.abort() 可以在請求完成前掛起請求。

目前, 在Firefox中有一個bug，雖然.getResponseHeader('Content-Type')返回一個非空的字符串，但是 .getAllResponseHeaders()還是返回空字符串， 在Firefox中使用jQuery不支持自動解碼JSON CORS 響應。

重寫jQuery.ajaxSettings.xhr 的一種解決方案，如下

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29

(function () { var _super = jQuery.ajaxSettings.xhr, xhrCorsHeaders = [ "Cache-Control", "Content-Language", "Content-Type", "Expires", "Last-Modified", "Pragma" ];   jQuery.ajaxSettings.xhr = function () { var xhr = _super(), getAllResponseHeaders = xhr.getAllResponseHeaders;   xhr.getAllResponseHeaders = function () { var allHeaders = ""; try { allHeaders = getAllResponseHeaders.apply( xhr ); if ( allHeaders ) { return allHeaders; } } catch ( e ) { }   $.each( xhrCorsHeaders, function ( i, headerName ) { if ( xhr.getResponseHeader( headerName ) ) { allHeaders += headerName + ": " + xhr.getResponseHeader( headerName ) + "\n"; } }); return allHeaders; };   return xhr; }; })();

Extending Ajax（擴展 Ajax）

從jQuery 1.5開始，，jQuery的Ajax實現包括預prefilters, transports和傳輸，讓您更加靈活的擴展Ajax。如需有關這些先進功能的信息，請參閱Extending Ajax

Using Converters（使用轉換器）

$.ajax()的轉換器支持的數據類型映射到其它數據類型。但是，如果你想把自定義數據類型映射到一個已知的類型（json等）,您必須contents 選項在響應的Content-Type和實際的數據類型之間的添加一個相關的轉換函數：

1 2 3 4 5 6 7 8 9 10 11

$.ajaxSetup({ contents: { mycustomtype: /mycustomtype/ }, converters: { "mycustomtype json": function ( result ) { // do stuff return newresult; } } });

這額外的對象是必要的，因為響應內容類型(Content-Types)和數據類型從來沒有一個嚴格的一對一對應關系（正則表達式表示結果）。

轉換一個支持的類型（例如text, json）成自定義數據類型，然后再返回，使用另一個直通轉換器：

1 2 3 4 5 6 7 8 9 10 11 12

$.ajaxSetup({ contents: { mycustomtype: /mycustomtype/ }, converters: { "text mycustomtype": true, "mycustomtype json": function ( result ) { // do stuff return newresult; } } });

現在上面的代碼允許通過從text 為mycustomtype ，進而，mycustomtype 轉換為 json。

Additional Notes:（其他注意事項：）

• 由於瀏覽器的安全限制，大多數“Ajax”的要求，均采用同一起源的政策 ;該請求不能成功地檢索來自不同的域，子域或協議的數據。
• Script和JSONP形式請求不受同源策略的限制。

 

例子:

Example: 保存數據到服務器，成功時顯示信息。

1 2 3 4 5 6 7

$.ajax({ method: "POST", url: "some.php", data: { name: "John", location: "Boston" } }).done(function( msg ) { alert( "Data Saved: " + msg ); });

Example: 裝入一個 HTML 網頁最新版本。

1 2 3 4 5 6

$.ajax({ url: "test.html", cache: false }).done(function( html ) { $("#results").append(html); });

Example: 發送 XML 數據至服務器。設置 processData 選項為 false，防止自動轉換數據格式。

1 2 3 4 5 6 7 8

var xmlDocument = [create xml document]; var xmlRequest = $.ajax({ url: "page.php", processData: false, data: xmlDocument });   xmlRequest.done(handleResponse);

Example: 發送id作為數據發送到服務器， 保存一些數據到服務器上， 並通一旦它的完成知用戶。  如果請求失敗，則提醒用戶。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

var menuId = $("ul.nav").first().attr("id"); var request = $.ajax({ url: "script.php", method: "POST", data: {id : menuId}, dataType: "html" });   request.done(function(msg) { $("#log").html( msg ); });   request.fail(function(jqXHR, textStatus) { alert( "Request failed: " + textStatus ); });

Example: 獲取json數據

1 2 3 4 5

$.ajax({ method: "GET", url: "service.php", dataType: "json", success:function(){}, error:function(){} });

Example: 載入並執行一個JavaScript文件.

1 2 3 4 5

$.ajax({ method: "GET", url: "test.js", dataType: "script" });