jQuery.ajax

jQuery.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格式的擴充。他要求一些伺服器端的代碼來檢測并處理查詢字元串參數。更多資訊可以參閱 最初的文章。

如果指定了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]ObjectV1.5

url:一個用來包含發送請求的URL字元串。

settings:AJAX 請求設定。所有選項都是可選的。

V1.0settings:選項

acceptsMap

預設： 取決于資料類型。

内容類型發送請求頭，告訴伺服器什麼樣的響應會接受傳回。如果accepts設定需要修改，推薦在$.ajaxSetup()方法中做一次。

asyncBoolean

(預設: true) 預設設定下，所有請求均為異步請求。如果需要發送同步請求，請将此選項設定為 false。注意，同步請求将鎖住浏覽器，使用者其它操作必須等待請求完成才可以執行。

beforeSend(XHR)Function

發送請求前可修改 XMLHttpRequest 對象的函數，如添加自定義 HTTP 頭。XMLHttpRequest 對象是唯一的參數。這是一個 Ajax 事件。如果傳回false可以取消本次ajax請求。            

function (XMLHttpRequest) {
    this; // 調用本次AJAX請求時傳遞的options參數
}      

cacheBoolean

(預設: true,dataType為script和jsonp時預設為false) jQuery 1.2 新功能，設定為 false 将不緩存此頁面。

complete(XHR, TS)Function

請求完成後回調函數 (請求成功或失敗之後均調用)。參數：  XMLHttpRequest 對象和一個描述成功請求類型的字元串。 Ajax 事件。            

function (XMLHttpRequest, textStatus) {
    this; // 調用本次AJAX請求時傳遞的options參數
}      

contentsMapV1.5

一個以"{字元串:正規表達式}"配對的對象，用來确定jQuery将如何解析響應，給定其内容類型。

contentTypeString

(預設: "application/x-www-form-urlencoded") 發送資訊至伺服器時内容編碼類型。預設值适合大多數情況。如果你明确地傳遞了一個content-type給 $.ajax() 那麼他必定會發送給伺服器（即使沒有資料要發送）

contextObject

這個對象用于設定Ajax相關回調函數的上下文。也就是說，讓回調函數内this指向這個對象（如果不設定這個參數，那麼this就指向調用本次AJAX請求時傳遞的options參數）。比如指定一個DOM元素作為context參數，這樣就設定了success回調函數的上下文為這個DOM元素。就像這樣：            

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

convertersmapV1.5

預設： {"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML}

一個資料類型對資料類型轉換器的對象。每個轉換器的值是一個函數，傳回響應的轉化值

crossDomainmapV1.5

預設： 同域請求為false

跨域請求為true如果你想強制跨域請求（如JSONP形式）同一域，設定crossDomain為true。這使得例如，伺服器端重定向到另一個域

dataObject,String

發送到伺服器的資料。将自動轉換為請求字元串格式。GET 請求中将附加在 URL 後。檢視 processData 選項說明以禁止此自動轉換。必須為 Key/Value 格式。如果為數組，jQuery 将自動為不同值對應同一個名稱。如 {foo:["bar1", "bar2"]} 轉換為 "&foo=bar1&foo=bar2"。

dataFilterFunction

給Ajax傳回的原始資料的進行預處理的函數。提供data和type兩個參數：data是Ajax傳回的原始資料，type是調用jQuery.ajax時提供的dataType參數。函數傳回的值将由jQuery進一步處理。            

function (data, type) {
    // 對Ajax傳回的原始資料進行預處理
    return data  // 傳回處理後的資料
}      

dataTypeString

預期伺服器傳回的資料類型。如果不指定，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": 傳回純文字字元串

errorFunction

(預設: 自動判斷 (xml 或 html)) 請求失敗時調用此函數。有以下三個參數：XMLHttpRequest 對象、錯誤資訊、（可選）捕獲的異常對象。如果發生了錯誤，錯誤資訊（第二個參數）除了得到null之外，還可能是"timeout", "error", "notmodified" 和 "parsererror"。Ajax 事件。            

function (XMLHttpRequest, textStatus, errorThrown) {
    // 通常 textStatus 和 errorThrown 之中
    // 隻有一個會包含資訊
    this; // 調用本次AJAX請求時傳遞的options參數
}      

globalBoolean

(預設: true) 是否觸發全局 AJAX 事件。設定為 false 将不會觸發全局 AJAX 事件，如 ajaxStart 或 ajaxStop 可用于控制不同的 Ajax 事件。

headersmapV1.5

Default: {}

一個額外的"{鍵:值}"對映射到請求一起發送。此設定被設定之前beforeSend函數被調用;是以，消息頭中的值設定可以在覆寫beforeSend函數範圍内的任何設定。

ifModifiedBoolean

(預設: false) 僅在伺服器資料改變時擷取新資料。使用 HTTP 包 Last-Modified 頭資訊判斷。在jQuery 1.4中，他也會檢查伺服器指定的'etag'來确定資料沒有被修改過。

isLocalmapV1.5.1

預設: 取決于目前的位置協定

允許目前環境被認定為“本地”，（如檔案系統），即使jQuery預設情況下不會承認它。以下協定目前公認為本地：file, *-extension, and widget。如果isLocal設定需要修改，建議在$.ajaxSetup()方法中這樣做一次。

jsonpString

在一個jsonp請求中重寫回調函數的名字。這個值用來替代在"callback=?"這種GET或POST請求中URL參數裡的"callback"部分，比如{jsonp:'onJsonPLoad'}會導緻将"onJsonPLoad=?"傳給伺服器。

jsonpCallbackString

為jsonp請求指定一個回調函數名。這個值将用來取代jQuery自動生成的随機函數名。這主要用來讓jQuery生成度獨特的函數名，這樣管理請求更容易，也能友善地提供回調函數和錯誤處理。你也可以在想讓浏覽器緩存GET請求的時候，指定這個回調函數名。

mimeTypeStringV1.5.1

一個mime類型用來覆寫XHR的 MIME類型。

passwordString

用于響應HTTP通路認證請求的密碼

processDataBoolean

(預設: true) 預設情況下，通過data選項傳遞進來的資料，如果是一個對象(技術上講隻要不是字元串)，都會處理轉化成一個查詢字元串，以配合預設内容類型 "application/x-www-form-urlencoded"。如果要發送 DOM 樹資訊或其它不希望轉換的資訊，請設定為 false。

scriptCharsetString

隻有當請求時dataType為"jsonp"或"script"，并且type是"GET"才會用于強制修改charset。通常隻在本地和遠端的内容編碼不同時使用。

statusCodemapV1.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 事件。            

function (data, textStatus) {
    // data 可能是 xmlDoc, jsonObj, html, text, 等等...
    this; // 調用本次AJAX請求時傳遞的options參數
}      

traditionalBoolean

如果你想要用傳統的方式來序列化資料，那麼就設定為true。請參考工具分類下面的jQuery.param 方法。

timeoutNumber

設定請求逾時時間（毫秒）。此設定将覆寫全局設定。

typeString

(預設: "GET") 請求方式 ("POST" 或 "GET")， 預設為 "GET"。注意：其它 HTTP 請求方法，如 PUT 和 DELETE 也可以使用，但僅部分浏覽器支援。

urlString

(預設: 目前頁位址) 發送請求的位址。

usernameString

用于響應HTTP通路認證請求的使用者名

xhrFunction

需要傳回一個XMLHttpRequest 對象。預設在IE下是ActiveXObject 而其他情況下是XMLHttpRequest 。用于重寫或者提供一個增強的XMLHttpRequest 對象。這個參數在jQuery 1.3以前不可用。

xhrFieldsmapV1.5

一對“檔案名-檔案值”在本機設定XHR對象。例如，如果需要的話，你可以用它來設定withCredentials為true的跨域請求。

示例

描述:

加載并執行一個 JS 檔案。

jQuery 代碼:

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

儲存資料到伺服器，成功時顯示資訊。

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

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

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

同步加載資料。發送請求時鎖住浏覽器。需要鎖定使用者互動操作時使用同步方式。

var html = $.ajax({  url: "some.php",  async: false }).responseText;           

發送 XML 資料至伺服器。設定 processData 選項為 false，防止自動轉換資料格式。

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