### 返回值:XMLHttpRequestjQuery.ajax(url,[settings]) ### 概述 通過 HTTP 請求加載遠程數據。 jQuery 底層 AJAX 實現。簡單易用的高層實現見 $.get, $.post 等。$.ajax() 返回其創建的 XMLHttpRequest 對象。大多數情況下你無需直接操作該函數，除非你需要操作不常用的選項，以獲得更多的靈活性。 最簡單的情況下，$.ajax()可以不帶任何參數直接使用。 **注意**，所有的選項都可以通過$.ajaxSetup()函數來全局設置。 **回調函數** 如果要處理$.ajax()得到的數據，則需要使用回調函數。beforeSend、error、dataFilter、success、complete。 - beforeSend 在發送請求之前調用，并且傳入一個XMLHttpRequest作為參數。 - error 在請求出錯時調用。傳入XMLHttpRequest對象，描述錯誤類型的字符串以及一個異常對象（如果有的話） - dataFilter 在請求成功之后調用。傳入返回的數據以及"dataType"參數的值。并且必須返回新的數據（可能是處理過的）傳遞給success回調函數。 - success 當請求之后調用。傳入返回后的數據，以及包含成功代碼的字符串。 - complete 當請求完成之后調用這個函數，無論成功或失敗。傳入XMLHttpRequest對象，以及一個包含成功或錯誤代碼的字符串。 **數據類型** $.ajax()函數依賴服務器提供的信息來處理返回的數據。如果服務器報告說返回的數據是XML，那么返回的結果就可以用普通的XML方法或者jQuery的選擇器來遍歷。如果見得到其他類型，比如HTML，則數據就以文本形式來對待。 通過dataType選項還可以指定其他不同數據處理方式。除了單純的XML，還可以指定 html、json、jsonp、script或者text。 其中，text和xml類型返回的數據不會經過處理。數據僅僅簡單的將XMLHttpRequest的responseText或responseHTML屬性傳遞給success回調函數， '''注意'''，我們必須確保網頁服務器報告的MIME類型與我們選擇的dataType所匹配。比如說，XML的話，服務器端就必須聲明 text/xml 或者 application/xml 來獲得一致的結果。 如果指定為html類型，任何內嵌的JavaScript都會在HTML作為一個字符串返回之前執行。類似的，指定script類型的話，也會先執行服務器端生成JavaScript，然后再把腳本作為一個文本數據返回。 如果指定為json類型，則會把獲取到的數據作為一個JavaScript對象來解析，并且把構建好的對象作為結果返回。為了實現這個目的，他首先嘗試使用JSON.parse()。如果瀏覽器不支持，則使用一個函數來構建。JSON數據是一種能很方便通過JavaScript解析的結構化數據。如果獲取的數據文件存放在遠程服務器上（域名不同，也就是跨域獲取數據），則需要使用jsonp類型。使用這種類型的話，會創建一個查詢字符串參數 callback=? ，這個參數會加在請求的URL后面。服務器端應當在JSON數據前加上回調函數名，以便完成一個有效的JSONP請求。如果要指定回調函數的參數名來取代默認的callback，可以通過設置$.ajax()的jsonp參數。 **注意**，JSONP是JSON格式的擴展。他要求一些服務器端的代碼來檢測并處理查詢字符串參數。更多信息可以參閱 [最初的文章](http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/)。 如果指定了script或者jsonp類型，那么當從服務器接收到數據時，實際上是用了<script>標簽而不是XMLHttpRequest對象。這種情況下，$.ajax()不再返回一個XMLHttpRequest對象，并且也不會傳遞事件處理函數，比如beforeSend。 **發送數據到服務器** 默認情況下，Ajax請求使用GET方法。如果要使用POST方法，可以設定type參數值。這個選項也會影響data選項中的內容如何發送到服務器。 data選項既可以包含一個查詢字符串，比如 key1=value1&key2=value2 ，也可以是一個映射，比如 {key1: 'value1', key2: 'value2'} 。如果使用了后者的形式，則數據再發送器會被轉換成查詢字符串。這個處理過程也可以通過設置processData選項為false來回避。如果我們希望發送一個XML對象給服務器時，這種處理可能并不合適。并且在這種情況下，我們也應當改變contentType選項的值，用其他合適的MIME類型來取代默認的 application/x-www-form-urlencoded 。 **高級選項** global選項用于阻止響應注冊的回調函數，比如.ajaxSend，或者ajaxError，以及類似的方法。這在有些時候很有用，比如發送的請求非常頻繁且簡短的時候，就可以在ajaxSend里禁用這個。更多關于這些方法的詳細信息，請參閱下面的內容。 如果服務器需要HTTP認證，可以使用用戶名和密碼可以通過username和password選項來設置。 Ajax請求是限時的，所以錯誤警告被捕獲并處理后，可以用來提升用戶體驗。請求超時這個參數通常就保留其默認值，要不就通過jQuery.ajaxSetup來全局設定，很少為特定的請求重新設置timeout選項。 默認情況下，請求總會被發出去，但瀏覽器有可能從他的緩存中調取數據。要禁止使用緩存的結果，可以設置cache參數為false。如果希望判斷數據自從上次請求后沒有更改過就報告出錯的話，可以設置ifModified為true。 scriptCharset允許給<script>標簽的請求設定一個特定的字符集，用于script或者jsonp類似的數據。當腳本和頁面字符集不同時，這特別好用。 Ajax的第一個字母是asynchronous的開頭字母，這意味著所有的操作都是并行的，完成的順序沒有前后關系。$.ajax()的async參數總是設置成true，這標志著在請求開始后，其他代碼依然能夠執行。強烈不建議把這個選項設置成false，這意味著所有的請求都不再是異步的了，這也會導致瀏覽器被鎖死。 $.ajax函數返回他創建的XMLHttpRequest對象。通常jQuery只在內部處理并創建這個對象，但用戶也可以通過xhr選項來傳遞一個自己創建的xhr對象。返回的對象通常已經被丟棄了，但依然提供一個底層接口來觀察和操控請求。比如說，調用對象上的.abort()可以在請求完成前掛起請求。 ### 參數 #### **url,[settings]**Object*V1.5* **url**:一個用來包含發送請求的URL字符串。 **settings**:AJAX 請求設置。所有選項都是可選的。 ### *V1.0***settings**:選項 #### **accepts**Map 默認： 取決于數據類型。 內容類型發送請求頭，告訴服務器什么樣的響應會接受返回。如果accepts設置需要修改，推薦在$.ajaxSetup()方法中做一次。 #### **async**Boolean (默認: true) 默認設置下，所有請求均為異步請求。如果需要發送同步請求，請將此選項設置為 false。注意，同步請求將鎖住瀏覽器，用戶其它操作必須等待請求完成才可以執行。 #### **beforeSend(XHR)**Function 發送請求前可修改 XMLHttpRequest 對象的函數，如添加自定義 HTTP 頭。XMLHttpRequest 對象是唯一的參數。這是一個 [Ajax 事件](http://docs.jquery.com/Ajax_Events "Ajax Events")。如果返回false可以取消本次ajax請求。 ~~~ function (XMLHttpRequest) { this; // 調用本次AJAX請求時傳遞的options參數 } ~~~ #### **cache**Boolean (默認: true,dataType為script和jsonp時默認為false) jQuery 1.2 新功能，設置為 false 將不緩存此頁面。 #### **complete(XHR, TS)**Function 請求完成后回調函數 (請求成功或失敗之后均調用)。參數： XMLHttpRequest 對象和一個描述成功請求類型的字符串。 [Ajax 事件](http://docs.jquery.com/Ajax_Events "Ajax Events")。 ~~~ function (XMLHttpRequest, textStatus) { this; // 調用本次AJAX請求時傳遞的options參數 } ~~~ #### **contents**Map*V1.5* 一個以"{字符串:正則表達式}"配對的對象，用來確定jQuery將如何解析響應，給定其內容類型。 #### **contentType**String (默認: "application/x-www-form-urlencoded") 發送信息至服務器時內容編碼類型。默認值適合大多數情況。如果你明確地傳遞了一個content-type給 $.ajax() 那么他必定會發送給服務器（即使沒有數據要發送） #### **context**Object 這個對象用于設置Ajax相關回調函數的上下文。也就是說，讓回調函數內this指向這個對象（如果不設定這個參數，那么this就指向調用本次AJAX請求時傳遞的options參數）。比如指定一個DOM元素作為context參數，這樣就設置了success回調函數的上下文為這個DOM元素。就像這樣： ~~~ $.ajax({ url: "test.html", context: document.body, success: function(){ $(this).addClass("done"); }}); ~~~ #### **converters**map*V1.5* 默認： {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML} 一個數據類型對數據類型轉換器的對象。每個轉換器的值是一個函數，返回響應的轉化值 #### **crossDomain**map*V1.5* 默認： 同域請求為false 跨域請求為true如果你想強制跨域請求（如JSONP形式）同一域，設置crossDomain為true。這使得例如，服務器端重定向到另一個域 #### **data**Object,String 發送到服務器的數據。將自動轉換為請求字符串格式。GET 請求中將附加在 URL 后。查看 processData 選項說明以禁止此自動轉換。必須為 Key/Value 格式。如果為數組，jQuery 將自動為不同值對應同一個名稱。如 {foo:["bar1", "bar2"]} 轉換為 "&foo=bar1&foo=bar2"。 #### **dataFilter**Function 給Ajax返回的原始數據的進行預處理的函數。提供data和type兩個參數：data是Ajax返回的原始數據，type是調用jQuery.ajax時提供的dataType參數。函數返回的值將由jQuery進一步處理。 ~~~ function (data, type) { // 對Ajax返回的原始數據進行預處理 return data // 返回處理后的數據 } ~~~ #### **dataType**String 預期服務器返回的數據類型。如果不指定，jQuery 將自動根據 HTTP 包 MIME 信息來智能判斷，比如XML MIME類型就被識別為XML。在1.4中，JSON就會生成一個JavaScript對象，而script則會執行這個腳本。隨后服務器端返回的數據會根據這個值解析后，傳遞給回調函數。可用值: "xml": 返回 XML 文檔，可用 jQuery 處理。 "html": 返回純文本 HTML 信息；包含的script標簽會在插入dom時執行。 "script": 返回純文本 JavaScript 代碼。不會自動緩存結果。除非設置了"cache"參數。'''注意：'''在遠程請求時(不在同一個域下)，所有POST請求都將轉為GET請求。(因為將使用DOM的script標簽來加載) "json": 返回 JSON 數據 。 "jsonp": [JSONP](http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/ "http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/") 格式。使用 [JSONP](http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/ "http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/") 形式調用函數時，如 "myurl?callback=?" jQuery 將自動替換 ? 為正確的函數名，以執行回調函數。 "text": 返回純文本字符串 #### **error**Function (默認: 自動判斷 (xml 或 html)) 請求失敗時調用此函數。有以下三個參數：XMLHttpRequest 對象、錯誤信息、（可選）捕獲的異常對象。如果發生了錯誤，錯誤信息（第二個參數）除了得到null之外，還可能是"timeout", "error", "notmodified" 和 "parsererror"。[Ajax 事件](http://docs.jquery.com/Ajax_Events "Ajax Events")。 ~~~ function (XMLHttpRequest, textStatus, errorThrown) { // 通常 textStatus 和 errorThrown 之中 // 只有一個會包含信息 this; // 調用本次AJAX請求時傳遞的options參數 } ~~~ #### **global**Boolean (默認: true) 是否觸發全局 AJAX 事件。設置為 false 將不會觸發全局 AJAX 事件，如 ajaxStart 或 ajaxStop 可用于控制不同的 [Ajax 事件](http://docs.jquery.com/Ajax_Events "Ajax Events")。 #### **headers**map*V1.5* Default: {} 一個額外的"{鍵:值}"對映射到請求一起發送。此設置被設置之前beforeSend函數被調用;因此，消息頭中的值設置可以在覆蓋beforeSend函數范圍內的任何設置。 #### **ifModified**Boolean (默認: false) 僅在服務器數據改變時獲取新數據。使用 HTTP 包 Last-Modified 頭信息判斷。在jQuery 1.4中，他也會檢查服務器指定的'etag'來確定數據沒有被修改過。 #### **isLocal**map*V1.5.1* 默認: 取決于當前的位置協議 允許當前環境被認定為“本地”，（如文件系統），即使jQuery默認情況下不會承認它。以下協議目前公認為本地：file, *-extension, and widget。如果isLocal設置需要修改，建議在$.ajaxSetup()方法中這樣做一次。 #### **jsonp**String 在一個jsonp請求中重寫回調函數的名字。這個值用來替代在"callback=?"這種GET或POST請求中URL參數里的"callback"部分，比如{jsonp:'onJsonPLoad'}會導致將"onJsonPLoad=?"傳給服務器。 #### **jsonpCallback**String 為jsonp請求指定一個回調函數名。這個值將用來取代jQuery自動生成的隨機函數名。這主要用來讓jQuery生成度獨特的函數名，這樣管理請求更容易，也能方便地提供回調函數和錯誤處理。你也可以在想讓瀏覽器緩存GET請求的時候，指定這個回調函數名。 #### **mimeType**String*V1.5.1* 一個mime類型用來覆蓋XHR的 MIME類型。 #### **password**String 用于響應HTTP訪問認證請求的密碼 #### **processData**Boolean (默認: true) 默認情況下，通過data選項傳遞進來的數據，如果是一個對象(技術上講只要不是字符串)，都會處理轉化成一個查詢字符串，以配合默認內容類型 "application/x-www-form-urlencoded"。如果要發送 DOM 樹信息或其它不希望轉換的信息，請設置為 false。 #### **scriptCharset**String 只有當請求時dataType為"jsonp"或"script"，并且type是"GET"才會用于強制修改charset。通常只在本地和遠程的內容編碼不同時使用。 #### **statusCode**map*V1.5* 默認: {} 一組數值的HTTP代碼和函數對象，當響應時調用了相應的代碼。例如，如果響應狀態是404，將觸發以下警報： ~~~ $.ajax({ statusCode: {404: function() { alert('page not found'); } }); ~~~ #### **success(data, textStatus, jqXHR)**Function,Array 請求成功后的回調函數。參數：由服務器返回，并根據dataType參數進行處理后的數據；描述狀態的字符串。還有 jqXHR（在jQuery 1.4.x的中，XMLHttpRequest） 對象 。在jQuery 1.5， 成功設置可以接受一個函數數組。每個函數將被依次調用。 [Ajax 事件](http://docs.jquery.com/Ajax_Events "Ajax Events")。 ~~~ function (data, textStatus) { // data 可能是 xmlDoc, jsonObj, html, text, 等等... this; // 調用本次AJAX請求時傳遞的options參數 } ~~~ #### **traditional**Boolean 如果你想要用傳統的方式來序列化數據，那么就設置為true。請參考工具分類下面的jQuery.param 方法。 #### **timeout**Number 設置請求超時時間（毫秒）。此設置將覆蓋全局設置。 #### **type**String (默認: "GET") 請求方式 ("POST" 或 "GET")， 默認為 "GET"。注意：其它 HTTP 請求方法，如 PUT 和 DELETE 也可以使用，但僅部分瀏覽器支持。 #### **url**String (默認: 當前頁地址) 發送請求的地址。 #### **username**String 用于響應HTTP訪問認證請求的用戶名 #### **xhr**Function 需要返回一個XMLHttpRequest 對象。默認在IE下是ActiveXObject 而其他情況下是XMLHttpRequest 。用于重寫或者提供一個增強的XMLHttpRequest 對象。這個參數在jQuery 1.3以前不可用。 #### **xhrFields**map*V1.5* 一對“文件名-文件值”在本機設置XHR對象。例如，如果需要的話，你可以用它來設置withCredentials為true的跨域請求。 ### 示例 #### 描述: 加載并執行一個 JS 文件。 ##### jQuery 代碼: ~~~ $.ajax({ type: "GET", url: "test.js", dataType: "script" }); ~~~ #### 描述: 保存數據到服務器，成功時顯示信息。 ##### jQuery 代碼: ~~~ $.ajax({ type: "POST", url: "some.php", data: "name=John&location=Boston", success: function(msg){ alert( "Data Saved: " + msg ); } }); ~~~ #### 描述: 裝入一個 HTML 網頁最新版本。 ##### jQuery 代碼: ~~~ $.ajax({ url: "test.html", cache: false, success: function(html){ $("#results").append(html); } }); ~~~ #### 描述: 同步加載數據。發送請求時鎖住瀏覽器。需要鎖定用戶交互操作時使用同步方式。 ##### jQuery 代碼: ~~~ var html = $.ajax({ url: "some.php", async: false }).responseText; ~~~ #### 描述: 發送 XML 數據至服務器。設置 processData 選項為 false，防止自動轉換數據格式。 ##### jQuery 代碼: ~~~ var xmlDocument = [create xml document]; $.ajax({ url: "page.php", processData: false, data: xmlDocument, success: handleResponse }); ~~~