首頁  >  ajax  > $.ajax(url,[settings])

返回值:XMLHttpRequest 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] 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 事件 。如果返回false可以取消本次ajax請求。

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

cache Boolean

(預設: true,dataType為script和jsonp時預設為false) jQuery 1.2 新功能,設定為 false 將不快取此頁面。

complete(XHR, TS) Function

請求完成後回撥函式 (請求成功或失敗之後均呼叫)。參數: XMLHttpRequest 對像和一個描述成功請求型別的字串。 Ajax 事件

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 格式。使用 JSONP 形式呼叫函式時,如 "myurl?callback=?" jQuery 將自動替換 ? 為正確的函式名,以執行回撥函式。

"text": 返回純文字字串

error Function

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

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

global Boolean

(預設: true) 是否觸發全域性 AJAX 事件。設定為 false 將不會觸發全域性 AJAX 事件,如 ajaxStart 或 ajaxStop 可用於控制不同的 Ajax 事件

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 事件

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
 });