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]

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

settings:AJAX 請求設置。全部選項都是可選的。

settings:選項

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

描述:

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

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