# jQuery ajax - ajax() 方法 ## 實例 通過 AJAX 加載一段文本： jQuery 代碼： ``` $(document).ready(function(){ $("#b01").click(function(){ htmlobj=$.ajax({url:"/jquery/test1.txt",async:false}); $("#myDiv").html(htmlobj.responseText); }); }); ``` HTML 代碼： ``` <div id="myDiv"><h2>Let AJAX change this text</h2></div> <button id="b01" type="button">Change Content</button> ``` ## 定義和用法 ajax() 方法通過 HTTP 請求加載遠程數據。 該方法是 jQuery 底層 AJAX 實現。簡單易用的高層實現見 $.get, $.post 等。$.ajax() 返回其創建的 XMLHttpRequest 對象。大多數情況下你無需直接操作該函數，除非你需要操作不常用的選項，以獲得更多的靈活性。 最簡單的情況下，$.ajax() 可以不帶任何參數直接使用。 注意：所有的選項都可以通過 $.ajaxSetup() 函數來全局設置。 ### 語法 ``` jQuery.ajax([_settings_]) ``` | 參數 | 描述 | | --- | --- | | _settings_ | 可選。用于配置 Ajax 請求的鍵值對集合。可以通過 $.ajaxSetup() 設置任何選項的默認值。 | ### 參數 options 類型：Object 可選。AJAX 請求設置。所有選項都是可選的。 async 類型：Boolean 默認值: true。默認設置下，所有請求均為異步請求。如果需要發送同步請求，請將此選項設置為 false。 注意，同步請求將鎖住瀏覽器，用戶其它操作必須等待請求完成才可以執行。 beforeSend(XHR) 類型：Function 發送請求前可修改 XMLHttpRequest 對象的函數，如添加自定義 HTTP 頭。 XMLHttpRequest 對象是唯一的參數。 這是一個 Ajax 事件。如果返回 false 可以取消本次 ajax 請求。 cache 類型：Boolean 默認值: true，dataType 為 script 和 jsonp 時默認為 false。設置為 false 將不緩存此頁面。 jQuery 1.2 新功能。 complete(XHR, TS) 類型：Function 請求完成后回調函數 (請求成功或失敗之后均調用)。 參數： XMLHttpRequest 對象和一個描述請求類型的字符串。 這是一個 Ajax 事件。 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"); }}); ``` data 類型：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 進一步處理。 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 格式。使用 JSONP 形式調用函數時，如 "myurl?callback=?" jQuery 將自動替換 ? 為正確的函數名，以執行回調函數。 * "text": 返回純文本字符串 error 類型：Function 默認值: 自動判斷 (xml 或 html)。請求失敗時調用此函數。 有以下三個參數：XMLHttpRequest 對象、錯誤信息、（可選）捕獲的異常對象。 如果發生了錯誤，錯誤信息（第二個參數）除了得到 null 之外，還可能是 "timeout", "error", "notmodified" 和 "parsererror"。 這是一個 Ajax 事件。 global 類型：Boolean 是否觸發全局 AJAX 事件。默認值: true。設置為 false 將不會觸發全局 AJAX 事件，如 ajaxStart 或 ajaxStop 可用于控制不同的 Ajax 事件。 ifModified 類型：Boolean 僅在服務器數據改變時獲取新數據。默認值: false。使用 HTTP 包 Last-Modified 頭信息判斷。在 jQuery 1.4 中，它也會檢查服務器指定的 'etag' 來確定數據沒有被修改過。 jsonp 類型：String 在一個 jsonp 請求中重寫回調函數的名字。這個值用來替代在 "callback=?" 這種 GET 或 POST 請求中 URL 參數里的 "callback" 部分，比如 {jsonp:'onJsonPLoad'} 會導致將 "onJsonPLoad=?" 傳給服務器。 jsonpCallback 類型：String 為 jsonp 請求指定一個回調函數名。這個值將用來取代 jQuery 自動生成的隨機函數名。這主要用來讓 jQuery 生成度獨特的函數名，這樣管理請求更容易，也能方便地提供回調函數和錯誤處理。你也可以在想讓瀏覽器緩存 GET 請求的時候，指定這個回調函數名。 password 類型：String 用于響應 HTTP 訪問認證請求的密碼 processData 類型：Boolean 默認值: true。默認情況下，通過data選項傳遞進來的數據，如果是一個對象(技術上講只要不是字符串)，都會處理轉化成一個查詢字符串，以配合默認內容類型 "application/x-www-form-urlencoded"。如果要發送 DOM 樹信息或其它不希望轉換的信息，請設置為 false。 scriptCharset 類型：String 只有當請求時 dataType 為 "jsonp" 或 "script"，并且 type 是 "GET" 才會用于強制修改 charset。通常只在本地和遠程的內容編碼不同時使用。 success 類型：Function 請求成功后的回調函數。 參數：由服務器返回，并根據 dataType 參數進行處理后的數據；描述狀態的字符串。 這是一個 Ajax 事件。 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 以前不可用。 ## 回調函數 如果要處理 $.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 格式的擴展。它要求一些服務器端的代碼來檢測并處理查詢字符串參數。 如果指定了 script 或者 jsonp 類型，那么當從服務器接收到數據時，實際上是用了 &lt;script&gt; 標簽而不是 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 允許給 &lt;script&gt; 標簽的請求設定一個特定的字符集，用于 script 或者 jsonp 類似的數據。當腳本和頁面字符集不同時，這特別好用。 Ajax 的第一個字母是 asynchronous 的開頭字母，這意味著所有的操作都是并行的，完成的順序沒有前后關系。$.ajax() 的 async 參數總是設置成true，這標志著在請求開始后，其他代碼依然能夠執行。強烈不建議把這個選項設置成 false，這意味著所有的請求都不再是異步的了，這也會導致瀏覽器被鎖死。 $.ajax 函數返回它創建的 XMLHttpRequest 對象。通常 jQuery 只在內部處理并創建這個對象，但用戶也可以通過 xhr 選項來傳遞一個自己創建的 xhr 對象。返回的對象通常已經被丟棄了，但依然提供一個底層接口來觀察和操控請求。比如說，調用對象上的 .abort() 可以在請求完成前掛起請求。