jquery ajax api

執行一個異步的HTTP（Ajax）的請求。

• version added: 1.5jQuery.ajax( url, [ settings ] )

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

  settings一個以"{鍵:值}"組成的AJAX 請求設置。全部選項都是可選的。可使用$.ajaxSetup()設置任何默認參數。看jQuery.ajax( settings )下全部設置的完整列表。

• version added: 1.0jQuery.ajax( settings )

  settings一個以"{鍵:值}"組成的AJAX 請求設置。全部選項都是可選的。可使用$.ajaxSetup()設置任何默認參數。

  acceptsMap

  默認： 取決於數據類型

  內容類型發送請求頭，告訴服務器什麼樣的響應會接受返回。若是accepts設置須要修改，推薦在$.ajaxSetup()方法中作一次。

  asyncBoolean

  默認： true

  默認設置下，全部請求均爲異步請求（也就是說這是默認設置爲true）。若是須要發送同步請求，請將此選項設置爲 false。跨域請求和dataType: "jsonp"請求不支持同步操做。注意，同步請求將鎖住瀏覽器，用戶其它操做必須等待請求完成才能夠執行。

  beforeSend(jqXHR, settings)Function

  發送請求前可修改 jqXHR（在jQuery 1.4.x的中，XMLHttpRequest） 對象的函數，如添加自定義 HTTP 頭等。該jqXHR和設置做爲參數傳遞的。這是一個Ajax事件 。beforeSend行數返回的false將取消該請求。在jQuery 1.5， beforeSend選項將被訪問，無論請求的類型。

  cacheBoolean

  默認： true, dataType爲"script"和"jsonp"時默認爲false

  若是設置爲 false ，瀏覽器將不緩存此頁面。

  complete(jqXHR, textStatus)Function, Array

  請求完成後回調函數 (請求成功或失敗以後均調用)。這個回調函數獲得2個參數： jqXHR (in jQuery 1.4.x, XMLHTTPRequest) 對象和一個描述成功請求類型的字符串("success", "notmodified", "error","timeout", or "parsererror") 。在jQuery 1.5， complete設置能夠接受一個函數的數組。每一個函數將被依次調用。這是一個Ajax事件 。

  contents(added 1.5)Map

  一個以"{字符串:正則表達式}"配對的對象，用來肯定jQuery將如何解析響應，給定其內容類型。

  contentTypeString

  默認: 'application/x-www-form-urlencoded'

  發送信息至服務器時內容編碼類型。默認值是"application/x-www-form-urlencoded"，適合大多數狀況。若是你明確地傳遞了一個content-type給 $.ajax() 那麼他一定會發送給服務器（即便沒有數據要發送）。數據將老是使用UTF-8字符集傳遞給服務器；你必須譯碼這適當的在服務器端。

  contextObject

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

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

  converters(1.5新增)Map

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

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

  crossDomain(1.5新增)

  默認： 同域請求爲false， 跨域請求爲true

  若是你想強制跨域請求（如JSONP形式）同一域，設置crossDomain爲true。這使得例如，服務器端重定向到另外一個域

  dataObject, String

  發送到服務器的數據。將自動轉換爲請求字符串格式。GET 請求中將附加在 URL 後。查看 processData 選項說明以禁止此自動轉換。必須爲"{鍵:值}"格式。若是爲數組，jQuery 將自動爲不一樣值對應同一個名稱。如 {foo:["bar1", "bar2"]} 轉換爲 '&foo=bar1&foo=bar2'。 若是值是一個數組（ Array ）, jQuery將在 多個連續的值具備相同的鍵值的基礎上創建的傳統設置(下述)。

  dataFilter(data, type)Function

  一個函數被用來處理XMLHttpRequest的原始響應數據。這是一個預過濾功能，淨化響應。您應該返回安全數據。提供data和type兩個參數：data是Ajax返回的原始數據，type是調用jQuery.ajax時提供的dataType參數。函數返回的值將由jQuery進一步處理。

  dataTypeString

  默認: Intelligent Guess (xml, json, script, or html)

  預期服務器返回的數據類型。若是不指定，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響應，並返回一個JavaScript對象。1.4中，JSON就會生成一個JavaScript對象，而script則會執行這個腳本。（見json.org的更多信息，正確的JSON格式。）
  • "jsonp": JSONP 格式。使用JSONP 形式調用函數時，如 "myurl?callback=?" jQuery 將自動替換 ? 爲正確的函數名，以執行回調函數。
  • "text": 返回純文本字符串。
  • 多個空格分割的值:As of jQuery 1.5， jQuery能夠從Content - Type頭收到並轉換一個您須要的數據類型。例如，若是你想要一個文本響應爲XML處理，使用"text xml"數據類型。您也能夠將一個JSONP的請求，以文本形式接受，並用jQuery以XML解析: "jsonp text xml"。一樣地可使用"jsonp xml"簡寫,將首先嚐試從JSONP形式轉換爲XML,作不到這一點，並無從文本，從JSONP形式轉換爲文本，而後到XML。

  error(jqXHR, textStatus, errorThrown)Function

  請求失敗時調用此函數。有如下三個參數：jqXHR (在 jQuery 1.4.x中, XMLHttpRequest) 對象、描述發生的錯誤類型的一個字符串和捕獲的異常對象。若是發生了錯誤，錯誤信息（第二個參數）除了獲得null以外，還多是"timeout", "error", "abort" 和 "parsererror"。這是一個 Ajax Event。 在jQuery 1.5, 在error設置能夠接受函數組成的數組。每一個函數將被依次調用。 注意：此處理程序不被跨域腳本和JSONP形式的請求調用。

  globalBoolean

  默認: true

  不管怎麼樣這個請求將觸發全局AJAX事件處理程序。默認是true 。設置爲 false 將不會觸發全局 AJAX 事件，如 ajaxStart 或 ajaxStop 可用於控制不一樣的。這能夠用來控制各類Ajax Events.

  headers(1.5新增)Map

  Default: {}

  一個額外的"{鍵:值}"對映射到請求一塊兒發送。此設置被設置以前beforeSend函數被調用;所以，消息頭中的值設置能夠在覆蓋beforeSend函數範圍內的任何設置。

  ifModifiedBoolean

  默認: false

  僅在服務器數據改變時獲取新數據。使用 HTTP 包 Last-Modified 頭信息判斷。在jQuery 1.4中，他也會檢查服務器指定的'etag'來肯定數據沒有被修改過。

  isLocal(added 1.5.1)Boolean

  默認: 取決於當前的位置協議

  容許當前環境被認定爲「本地」，（如文件系統），即便jQuery默認狀況下不會認可它。如下協議目前公認爲本地：file, *-extension, and widget。若是isLocal設置須要修改，建議在$.ajaxSetup()方法中這樣作一次。

  jsonpString

  在一個jsonp請求中重寫回調函數的名字。這個值用來替代在"callback=?"這種GET或POST請求中URL參數裏的"callback"部分，好比{jsonp:'onJsonPLoad'}會致使將"onJsonPLoad=?"傳給服務器。在jQuery 1.5，，設置jsonp選項爲false阻止了jQuery從加入"?callback"字符串的URL或試圖使用"=?"轉換。在這種狀況下，你也應該明確設置jsonpCallback設置。例如, { jsonp: false, jsonpCallback: "callbackName" }

  jsonpCallbackString, Function

  爲jsonp請求指定一個回調函數名。這個值將用來取代jQuery自動生成的隨機函數名。這主要用來讓jQuery生成度獨特的函數名，這樣管理請求更容易，也能方便地提供回調函數和錯誤處理。你也能夠在想讓瀏覽器緩存GET請求的時候，指定這個回調函數名。在jQuery 1.5，你也可使用一個函數值該設置，在這種狀況下jsonpCallback的值設置到該函數的返回值。

  mimeType(added 1.5.1)String

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

  passwordString

  用於響應HTTP訪問認證請求的密碼

  processDataBoolean

  默認: true

  默認狀況下，經過data選項傳遞進來的數據，若是是一個對象(技術上講只要不是字符串)，都會處理轉化成一個查詢字符串，以配合默認內容類型 "application/x-www-form-urlencoded"。若是要發送 DOM 樹信息或其它不但願轉換的信息，請設置爲 false。

  scriptCharsetString

  只有當請求時dataType爲"jsonp"或"script"，而且type是"GET"纔會用於強制修改charset。一般只在本地和遠程的內容編碼不一樣時使用。

  statusCode(1.5新增)Map

  默認: {}

  一組數值的HTTP代碼和函數對象，當響應時調用了相應的代碼。例如，若是響應狀態是404，將觸發如下警報：

  $.ajax({
    statusCode: {404: function() {
      alert('page not found');
    }
  });

  若是請求成功，狀態代碼函數做爲回調的成功相同的參數;若是在一個錯誤的結果，他們採起了相同的參數error回調。

  success(data, textStatus, jqXHR)Function, Array

  請求成功後的回調函數。這個函數傳遞3個參數：從服務器返回的數據，並根據dataType參數進行處理後的數據，一個描述狀態的字符串;還有 jqXHR（在jQuery 1.4.x的中，XMLHttpRequest） 對象 。在jQuery 1.5， 成功設置能夠接受一個函數數組。每一個函數將被依次調用。這是一個 Ajax Event.

  timeoutNumber

  設置請求超時時間（毫秒）。若是一個設置有$.ajaxSetup()，此設置將覆蓋全局設置。例如，你可使用這個屬性來提供一個單一的請求比全部你所設置時間在一秒鐘內的其餘要求更長的超時。見$.ajaxSetup()全局超時。

  traditionalBoolean

  若是你想要用傳統的方式來序列化數據，那麼就設置爲true。請參考工具分類下面的jQuery.param 方法.

  typeString

  默認: 'GET'

  請求方式 ("POST" 或 "GET")， 默認爲 "GET"。注意：其它 HTTP 請求方法，如 PUT 和 DELETE 也可使用，但僅部分瀏覽器支持。

  urlString

  默認: 當前地址

  發送請求的地址。

  usernameString

  於響應HTTP訪問認證請求的用戶名

  xhrFunction

  默認 當可用的ActiveXObject（IE）中，不然爲XMLHttpRequest

  回調建立XMLHttpRequest對象。當可用時默認爲ActiveXObject（IE）中，不然爲XMLHttpRequest。提供覆蓋你本身的執行的XMLHttpRequest或加強工廠。

  xhrFields(added 1.5.1)Map

  一對「文件名-文件值」在本機設置XHR對象。例如，若是須要的話，你能夠用它來設置withCredentials爲true的跨域請求。

$.ajax()函數全部的基礎jQuery的Ajax請求發送。它每每不是必須的，直接調用這個函數，幾個高層次的替代品如$.get()和.load()可用，更容易使用，若是不常見的選項是必需的，不過， $.ajax()可使用更靈活。

在簡單地說， $.ajax()函數能夠不帶參數調用：

$.ajax();

注意: 全部的選項均可以經過$.ajaxSetup() 函數來全局設置

這個例子中，不使用選項，加載當前頁面的內容，但其結果沒有。若要使用結果，咱們能夠實現的回調功能之一。

jqXHR 對象

該jQuery的XMLHttpRequest（jqXHR）對象返回$.ajax() 在jQuery 1.5是一個對象的超集瀏覽器的原生的XMLHttpRequest。例如，它包含responseText和responseXML性能，以及一個getResponseHeader()方法。當傳輸機制是XMLHttpRequest之外的東西（例如，一個一個JSONP請求腳本標籤）的jqXHR對象儘量的模擬原生的XHR功能。

在jQuery 1.5.1， 在jqXHR對象還包含了overrideMimeType方法。

$.ajax()返回的jqXHR對象 實現約定的接口，給他們的全部屬性，方法，和約定的行爲（見Deferred object獲取更多信息）。爲了方便和一致性$.ajax()回調函數名稱中使用。jqXHR也提供.error() .success()和.complete()方法。這些方法當$.ajax()請求終止時須要一個函數參數調用，這個函數接收$.ajax()回調函數名相同的參數。在jQuery 1.5這容許你指定一個請求的多個回調，甚至可能分配請求後已完成回調。（若是請求已經完成，回調當即觸發。）

// Assign handlers immediately after making the request,
// and remember the jqxhr object for this request
var jqxhr = $.ajax({ url: "example.php" })
    .success(function() { alert("success"); })
    .error(function() { alert("error"); })
    .complete(function() { alert("complete"); });

// perform other work here ...

// Set another completion function for the request above
jqxhr.complete(function(){ alert("second complete"); });

爲了向後兼容XMLHttpRequest ，一jqXHR對象將公開下列屬性和方法：

• readyState
• status
• statusText
• responseXML and/or responseText 當底層的請求分別做出XML和/或文本響應
• setRequestHeader(name, value) 這背離了換上了新一舊的價值，而不是串聯的新值與舊標準
• getAllResponseHeaders()
• getResponseHeader()
• abort()

假如沒有onreadystatechange機制，無論怎樣 因爲success ， error ， complete和statusCode覆蓋全部可能的要求。

回調函數

若是要處理$.ajax()獲得的數據，則須要使用回調函數。beforeSend、error、dataFilter、success、complete。

在jQuery 1.5， error ， success ，和complete回調鉤子先入先出隊列管理。這意味着你能夠爲每一個掛鉤分配多個回調。見Deferred object methods ，這是實現內部的$.ajax()回調掛鉤。

在this回調是在全部參考對象在context選項傳遞給$.ajax在設置;若是context沒有指定， this是他們本身的Ajax設置參考。

某些類型Ajax的請求，如JSONP形式和跨域的GET請求，請不要使用XHR;在這些狀況下XMLHttpRequest和textStatus參數傳遞給回調是undefined 。

這裏有$.ajax()提供的鉤子回調 ：

1. beforeSend 在發送請求以前調用，它接收jqXHR對象和settings做爲參數對象。
2. error 在請求出錯時調用。若是請求失敗，在它們的順序依次登記。他們收到jqXHR ，字符串表示的錯誤類型，若是適用的異常對象。一些內置的錯誤，將提供做爲例外對象的字符串： "abort", "timeout", "No Transport"。
3. dataFilter 在請求成功以後調用。傳入返回的數據以及dataType參數的值。而且必須返回新的數據（多是處理過的）傳遞給success回調函數。
4. success 當請求以後調用。傳入返回後的數據，以及包含成功代碼的字符串。他們收到返回的數據，一個包含成功的代碼和jqXHR對象。
5. complete 它們的順序依次登記回調，請求完成時，不管是在失敗或成功。他們收到jqXHR對象，以及一個包含成功或錯誤代碼。

For example, 經過使用返回的HTML，咱們能夠實現一個success事件處理器：

$.ajax({
  url: 'ajax/test.html',
  success: function(data) {
    $('.result').html(data);
    alert('Load was performed.');
  }
});

數據類型

$.ajax()函數依賴服務器提供的信息來處理返回的數據。若是服務器報告說返回的數據是XML，那麼返回的結果就能夠用普通的XML方法或者jQuery的選擇器來遍歷。若是見獲得其餘類型，好比HTML，則數據就以文本形式來對待。

經過dataType選項還能夠指定其餘不一樣數據處理方式。除了單純的XML，還能夠指定 html、json、jsonp、script或者text。

其中，text和xml類型返回的數據不會通過處理。這些數據僅僅是傳遞給處理程序的成功，不管是經過responseText或responseXML全部的jqXHR對象。

注意:咱們必須確保網頁服務器報告的MIME類型與咱們選擇的dataType所匹配。好比說，XML的話，服務器端就必須聲明 text/xml 或者 application/xml 來得到一致的結果。

若是指定爲 html類型，任何內嵌的JavaScript都會在HTML做爲一個字符串返回以前執行。相似的，指定script類型的話，也會先執行服務器端生成JavaScript，而後再把腳本做爲一個文本數據返回。

若是指定爲json類型，則會把獲取到的數據做爲一個JavaScript對象來解析，而且把構建好的對象做爲結果返回。爲了實現這個目的，他首先嚐試使用jQuery.parseJSON()。若是瀏覽器不支持，則使用一個Function來構建。JSON數據是一種能很方便經過JavaScript解析的結構化數據。若是獲取的數據文件存放在遠程服務器上（域名不一樣，也就是跨域獲取數據），則須要使用jsonp類型。使用這種類型的話，會建立一個查詢字符串參數 callback=? ，這個參數會加在請求的URL後面。服務器端應當在JSON數據前加上回調函數名，以便完成一個有效的JSONP請求。若是要指定回調函數的參數名來取代默認的callback，能夠經過設置$.ajax()的jsonp參數。

注意:JSONP是JSON格式的擴展。他要求一些服務器端的代碼來檢測並處理查詢字符串參數。更多信息能夠參閱original post detailing its use.

若是指定了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()能夠在請求完成前掛起請求。

擴展的Ajax

在jQuery 1.5，，jQuery的Ajax實現包括預過濾器，轉換器和傳輸，讓您擴展了很大的靈活性Ajax。如需有關這些先進功能的信息，請參閱Extending Ajax

其餘注意事項：

• 因爲瀏覽器的安全限制，大多數「Ajax」的要求，均採用同一塊兒源的政策 ;該請求不能成功地檢索來自不一樣的域，子域或協議的數據。
• Script和JSONP形式請求不受同源策略的限制。

Examples:

Example: 加載並執行一個 JS 文件。

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

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

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

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

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

Example: 同步加載數據。發送請求時鎖住瀏覽器。須要鎖定用戶交互操做時使用同步方式。

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

Example: 發送 XML 數據至服務器。設置 processData 選項爲 false，防止自動轉換數據格式。

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

Example: 做爲發送數據到服務器的ID，保存一些數據到服務器，並通知用戶一旦它的完成。請注意，此用法 - 返回到一個變量的調用的結果 - 須要同步（阻塞）的要求！ （異步：假）

bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      async:false,
      success: function(msg){
         alert(msg);
      }
   }
).responseText;

本文轉自：http://www.jb51.net/shouce/jQuery-1.6-api/#p=jQuery.ajax