JQuery jQuery.ajax()用法及代碼示例

說明：執行異步 HTTP (Ajax) 請求。

• 添加的版本：1.5jQuery.ajax( url [, settings ] )

  • url
    類型：String
    包含請求發送到的 URL 的字符串。
  • settings
    類型：PlainObject
    一組配置 Ajax 請求的鍵/值對。所有設置都是可選的。可以使用 $.ajaxSetup() 為任何選項設置默認值。有關所有設置的完整列表，請參閱下麵的jQuery.ajax( settings )。

• 添加的版本：1.0jQuery.ajax( [settings ] )

  • settings
    類型：PlainObject
    一組配置 Ajax 請求的鍵/值對。所有設置都是可選的。可以使用 $.ajaxSetup() 為任何選項設置默認值。
    • accepts(默認：depends on dataType)
      類型：PlainObject
      一組映射給定的鍵/值對dataType到它的 MIME 類型，它在Accept請求標頭。這個標頭告訴服務器它將接受什麽樣的響應作為返回。例如下麵定義了一個自定義類型mycustomtype與請求一起發送：

      $.ajax({ accepts: { mycustomtype: 'application/x-some-custom-type' }, // Instructions for how to deserialize a `mycustomtype` converters: { 'text mycustomtype': function(result) { // Do Stuff return newresult; } }, // Expect a `mycustomtype` back from server dataType: 'mycustomtype' });

      Note:您需要為此類型指定一個補充條目converters使其正常工作。
    • async(默認：true)
      類型：Boolean
      默認情況下，所有請求都是異步發送的(即設置為true默認情況下)。如果您需要同步請求，請將此選項設置為false. Cross-domain 請求和dataType: "jsonp"請求不支持同步操作。請注意，同步請求可能會暫時鎖定瀏覽器，從而在請求處於活動狀態時禁用任何操作。As of jQuery 1.8， 指某東西的用途async: false與 jqXHR ($.Deferred)已棄用；您必須使用成功/錯誤/完成回調選項而不是 jqXHR 對象的相應方法，例如jqXHR.done().
    • beforeSend
      類型：Function(jqXHRjqXHR，PlainObject設置)
      一個預請求回調函數，可用於在發送之前修改 jqXHR(在 jQuery 1.4.x 中為 XMLHTTPRequest)對象。使用它來設置自定義標題等。 jqXHR 和設置對象作為參數傳遞。這是個阿賈克斯事件.返回false在裏麵beforeSend函數將取消請求。As of jQuery 1.5， 這beforeSend無論請求的類型如何，都會調用選項。
    • cache(默認：true, false for dataType 'script' and 'jsonp')
      類型：Boolean
      如果設置為false，它將強製瀏覽器不緩存請求的頁麵。Note:環境cache設置為 false 僅適用於 HEAD 和 GET 請求。它通過將 "_={timestamp}" 附加到 GET 參數來工作。其他類型的請求不需要該參數，除非在 IE8 中對已由 GET 請求的 URL 進行 POST。
    • complete
      類型：Function(jqXHRjqXHR，StringtextStatus)
      請求完成時調用的函數(之後success和error回調被執行)。該函數被傳遞了兩個參數：jqXHR(在 jQuery 1.4.x 中，XMLHTTPRequest)對象和一個對請求狀態進行分類的字符串("success","notmodified","nocontent","error","timeout","abort"， 或者"parsererror")。As of jQuery 1.5， 這completesetting 可以接受一個函數數組。每個函數都會被依次調用。這是個阿賈克斯事件.
    • contents
      類型：PlainObject
      字符串/regular-expression 對的對象，根據其內容類型確定 jQuery 如何解析響應。(添加的版本：1.5)
    • contentType(默認：'application/x-www-form-urlencoded; charset=UTF-8')
      類型：Boolean 或 String
      向服務器發送數據時，使用此內容類型。默認為“application/x-www-form-urlencoded; charset=UTF-8”，這在大多數情況下都可以。如果您明確地將 content-type 傳遞給$.ajax()，那麽它總是被發送到服務器(即使沒有發送數據)。從 jQuery 1.6 開始，您可以通過false告訴 jQuery 不要設置任何內容類型標頭。Note:W3C XMLHttpRequest 規範規定字符集始終為 UTF-8；指定另一個字符集不會強製瀏覽器更改編碼。Note:對於 cross-domain 請求，將內容類型設置為除application/x-www-form-urlencoded,multipart/form-data， 或者text/plain將觸發瀏覽器向服務器發送預檢 OPTIONS 請求。
    • context
      類型：PlainObject
      該對象將是所有Ajax-related 回調的上下文。默認情況下，上下文是一個對象，表示調用中使用的 Ajax 設置 ($.ajaxSettings與傳遞給的設置合並$.ajax)。例如，指定一個 DOM 元素作為上下文將使complete請求的回調，如下所示：

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

    • converters(默認：{"* text": window.String, "text html": true, "text json": jQuery.parseJSON, "text xml": jQuery.parseXML})
      類型：PlainObject
      包含dataType-to-dataType 轉換器的對象。每個轉換器的值都是一個返回響應的轉換值的函數。(添加的版本：1.5)
    • crossDomain(默認：false for same-domain requests, true for cross-domain requests)
      類型：Boolean
      如果您希望在同一域上強製執行跨域請求(例如 JSONP)，請將 crossDomain 的值設置為true.例如，這允許服務器端重定向到另一個域。(添加的版本：1.5)
    • data
      類型：PlainObject 或 String 或 Array

      要發送到服務器的數據。如果 HTTP 方法不能具有實體主體，例如 GET，則將 data 附加到 URL。

      當 data 是一個對象時，jQuery 從對象的鍵/值對生成數據字符串，除非 processData 選項設置為 false 。例如，{ a: "bc", d: "e,f" } 被轉換為字符串 "a=bc&d=e%2Cf" 。如果值是一個數組，jQuery 會根據 traditional 設置的值(如下所述)使用相同的鍵序列化多個值。例如，{ a: [1,2] } 變為字符串 "a%5B%5D=1&a%5B%5D=2"，默認設置為 traditional: false。

      什麽時候data作為字符串傳遞，它應該已經被編碼使用正確的編碼contentType，默認情況下是application/x-www-form-urlencoded.

      在帶有 dataType: "json" 或 dataType: "jsonp" 的請求中，如果字符串在 URL 中的任何位置包含雙問號 ( ?? ) 或在查詢字符串中包含單個問號 ( ? )，則將其替換為生成的值通過 jQuery 對頁麵上的每個庫副本都是唯一的(例如 jQuery21406515378922229067_1479880736745 )。

    • dataFilter
      類型：Function(String 數據，String 類型)=> Anything
      用於處理 XMLHttpRequest 的原始響應數據的函數。這是一個預過濾函數，用於清理響應。您應該返回經過清理的數據。該函數接受兩個參數：從服務器返回的原始數據和'dataType' 參數。
    • dataType(默認：Intelligent Guess (xml, json, script, or html))
      類型：String
      您期望從服務器返回的數據類型。如果沒有指定，jQuery 將嘗試根據響應的 MIME 類型推斷它(XML MIME 類型將產生 XML，在 1.4 中 JSON 將產生一個 JavaScript 對象，在 1.4 中腳本將執行腳本，其他任何東西都會作為字符串返回)。可用的類型(以及作為第一個參數傳遞給成功回調的結果)是：

      • "xml" ：返回可以通過 jQuery 處理的 XML 文檔。
      • "html" ：將 HTML 作為純文本返回；包含的腳本標簽在插入 DOM 時進行評估。
      • "script"：將響應評估為 JavaScript 並將其作為純文本返回。通過附加查詢字符串參數來禁用緩存，_=[TIMESTAMP], 到 URL，除非cache選項設置為true.Note:這會將 remote-domain 請求的 POST 轉換為 GET。在 jQuery 3.5.0 之前，使用腳本的 HTTP 響應不成功Content-Type仍然被處決。
      • "json" ：將響應評估為 JSON 並返回一個 JavaScript 對象。 Cross-domain "json" 請求具有回調占位符，例如?callback=? 使用 JSONP 執行，除非請求在其請求選項中包含 jsonp: false。 JSON數據被嚴格解析；任何格式錯誤的 JSON 都會被拒絕並引發解析錯誤。從 jQuery 1.9 開始，空響應也會被拒絕；服務器應該返回 null 或 {} 的響應。 (有關正確的 JSON 格式的更多信息，請參閱json.org。)
      • "jsonp" ：使用 JSONP 加載到 JSON 塊中。在 URL 的末尾添加一個額外的 "?callback=?" 以指定回調。通過將查詢字符串參數 "_=[TIMESTAMP]" 附加到 URL 來禁用緩存，除非 cache 選項設置為 true。
      • "text" ：純文本字符串。
      • 多個空格分隔的值：從 jQuery 1.5 開始, jQuery 可以將 Content-Type 標頭中收到的數據類型轉換為您需要的數據類型。例如，如果您希望將文本響應視為 XML，請使用"text xml"對於數據類型。您還可以發出 JSONP 請求，將其作為文本接收，並由 jQuery 解釋為 XML："jsonp text xml".類似地，一個速記字符串如"jsonp xml"將首先嘗試從 jsonp 轉換為 xml，如果失敗，則從 jsonp 轉換為文本，然後從文本轉換為 xml。
    • error
      類型：Function(jqXHRjqXHR，StringtextStatus，StringerrorThrown)
      請求失敗時調用的函數。該函數接收三個參數：jqXHR(在 jQuery 1.4.x 中，XMLHttpRequest)對象，一個說明發生的錯誤類型的字符串和一個可選的異常對象(如果發生)。第二個參數的可能值(除了null) 是"timeout","error","abort"， 和"parsererror".發生 HTTP 錯誤時，errorThrown接收 HTTP 狀態的文本部分，例如 "Not Found" 或“內部服務器錯誤”。 (在 HTTP/2 中它可能是一個空字符串)As of jQuery 1.5， 這errorsetting 可以接受一個函數數組。每個函數都會被依次調用。Note: This handler is not called for cross-domain script and cross-domain JSONP requests.這是個阿賈克斯事件.
    • global(默認：true)
      類型：Boolean
      是否為此請求觸發全局 Ajax 事件處理程序。默認值為 true 。設置為 false 以防止觸發 ajaxStart 或 ajaxStop 等全局處理程序。這可用於控製各種 Ajax Events 。
    • headers(默認：{})
      類型：PlainObject
      使用 XMLHttpRequest 傳輸與請求一起發送的附加標頭鍵/值對的對象。標題X-Requested-With: XMLHttpRequest總是添加，但它的默認值XMLHttpRequest值可以在這裏更改。中的值headers設置也可以從內部覆蓋beforeSend函數。(添加的版本：1.5)
    • ifModified(默認：false)
      類型：Boolean
      僅當自上次請求以來響應已更改時，才允許請求成功。這是通過檢查Last-Modified 標頭來完成的。默認值為 false ，忽略標題。在 jQuery 1.4 中，此技術還檢查服務器指定的 'etag' 以捕獲未修改的數據。
    • isLocal(默認：depends on current location protocol)
      類型：Boolean
      允許當前環境被識別為"local,"(例如文件係統)，即使默認情況下 jQuery 不識別它。以下協議目前被認為是本地的：file,*-extension， 和widget.如果isLocal設置需要修改，建議修改一次$.ajaxSetup()方法。(添加的版本：1.5.1)
    • jsonp
      類型：String 或 Boolean
      覆蓋 JSONP 請求中的回調函數名稱。在 url 中查詢字符串的 'callback=?' 部分中，將使用此值而不是 'callback'。所以{jsonp:'onJSONPLoad'}會導致'onJSONPLoad=?'傳遞給服務器。As of jQuery 1.5, 設置jsonp選項false防止 jQuery 將 "?callback" 字符串添加到 URL 或嘗試使用 "=?" 進行轉換。在這種情況下，您還應該顯式設置jsonpCallback環境。例如，{ jsonp: false, jsonpCallback: "callbackName" }.如果您不信任 Ajax 請求的目標，請考慮設置jsonp屬性false出於安全原因。
    • jsonpCallback
      類型：String 或 Function ()
      指定 JSONP 請求的回調函數名稱。將使用此值代替 jQuery 自動生成的隨機名稱。最好讓 jQuery 生成一個唯一的名稱，因為這樣可以更輕鬆地管理請求並提供回調和錯誤處理。當您想要啟用更好的 GET 請求瀏覽器緩存時，您可能需要指定回調。As of jQuery 1.5, 你也可以使用一個函數來進行這個設置, 在這種情況下, 的值jsonpCallback設置為該函數的返回值。
    • method(默認：'GET')
      類型：String
      用於請求的 HTTP 方法(例如"POST","GET","PUT")。(添加的版本：1.9.0)
    • mimeType
      類型：String
      要覆蓋的 mime 類型XHR啞劇類型。(添加的版本：1.5.1)
    • password
      類型：String
      與 XMLHttpRequest 一起使用以響應 HTTP 訪問身份驗證請求的密碼。
    • processData(默認：true)
      類型：Boolean
      默認情況下，作為對象傳遞給data 選項的數據(從技術上講，是字符串以外的任何內容)將被處理並轉換為查詢字符串，以適應默認的content-type“application/x-www-form-urlencoded”。如果要發送 DOMDocument 或其他未處理的數據，請將此選項設置為 false 。
    • scriptAttrs
      類型：PlainObject
      定義要在 "script" 或 "jsonp" 請求中使用的具有附加屬性的對象。鍵代表屬性的名稱，值是屬性的值。如果提供此對象，它將強製使用script-tag 傳輸。例如，這可以用來設置nonce,integrity， 或者crossorigin屬性以滿足內容安全策略要求。(添加的版本：3.4.0)
    • scriptCharset
      類型：String
      僅在使用 "script" 傳輸時適用。在請求中使用的腳本標記上設置 charset 屬性。當本地頁麵上的字符集與遠程腳本上的字符集不同時使用。或者，可以在scriptAttrs 中指定charset 屬性，這也將確保使用"script" 傳輸。
    • statusCode(默認：{})
      類型：PlainObject

      響應具有相應代碼時要調用的數字 HTTP 代碼和函數的對象。例如，以下將在響應狀態為 404 時發出警報：

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

      如果請求成功，狀態碼函數采用與成功回調相同的參數；如果它導致錯誤(包括 3xx 重定向)，它們采用與 error 回調相同的參數。

      (添加的版本：1.5)
    • success
      類型：Function(Anything數據，String文本狀態，jqXHRjqXHR)
      請求成功時調用的函數。該函數傳遞了三個參數： 從服務器返回的數據，根據dataType參數或dataFilter回調函數，如果指定；說明狀態的字符串；和jqXHR(在 jQuery 1.4.x 中，XMLHttpRequest)對象。As of jQuery 1.5,the success setting can accept an array of functions. Each function will be called in turn.這是個阿賈克斯事件.
    • timeout
      類型：Number
      為請求設置超時(以毫秒為單位)。值為 0 表示不會有超時。這將覆蓋任何全局超時設置jQuery.ajaxSetup().超時時間從點開始$.ajax撥調用；如果有幾個其他請求正在進行並且瀏覽器沒有可用的連接，則請求可能會在發送之前超時。In jQuery 1.4.x and below,如果請求超時，XMLHttpRequest 對象將處於無效狀態；訪問任何對象成員都可能引發異常。In Firefox 3.0+ only,腳本和 JSONP 請求不能被超時取消；即使腳本在超時期限之後到達，它也會運行。
    • traditional
      類型：Boolean
      如果您希望使用 param serialization 的傳統樣式，請將其設置為 true 。
    • type(默認：'GET')
      類型：String
      method 的別名。如果您使用的是 1.9.0 之前的 jQuery 版本，則應該使用 type。
    • url(默認：The current page)
      類型：String
      包含請求發送到的 URL 的字符串。
    • username
      類型：String
      與 XMLHttpRequest 一起使用以響應 HTTP 訪問身份驗證請求的用戶名。
    • xhr(默認：ActiveXObject when available (IE), the XMLHttpRequest otherwise)
      類型：Function ()
      創建 XMLHttpRequest 對象的回調。可用時默認為 ActiveXObject (IE)，否則默認為 XMLHttpRequest。重寫以提供您自己的 XMLHttpRequest 實現或對工廠的增強。
    • xhrFields
      類型：PlainObject

      fieldName-fieldValue 對的對象設置在本機 XHR 對象上。例如，如果需要，您可以使用它為cross-domain 請求將withCredentials 設置為true。

      $.ajax({ url: a_cross_domain_url, xhrFields: { withCredentials: true } });

      在 jQuery 1.5 中， 這withCredentials屬性未傳播到本地XHR因此需要它的 CORS 請求將忽略此標誌。因此，如果您需要使用 jQuery 1.5.1+，我們建議您使用它。

      (添加的版本：1.5.1)

$.ajax();

$.ajax({
  url: "https://fiddle.jshell.net/favicon.png",
  beforeSend: function( xhr ) {
    xhr.overrideMimeType( "text/plain; charset=x-user-defined" );
  }
})
  .done(function( data ) {
    if ( console && console.log ) {
      console.log( "Sample of data:", data.slice( 0, 100 ) );
    }
  });

// Assign handlers immediately after making the request,
// and remember the jqXHR object for this request
var jqxhr = $.ajax( "example.php" )
  .done(function() {
    alert( "success" );
  })
  .fail(function() {
    alert( "error" );
  })
  .always(function() {
    alert( "complete" );
  });
 
// Perform other work here ...
 
// Set another completion function for the request above
jqxhr.always(function() {
  alert( "second complete" );
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "mycustomtype json": function( result ) {
      // Do stuff
      return newresult;
    }
  }
});

$.ajaxSetup({
  contents: {
    mycustomtype: /mycustomtype/
  },
  converters: {
    "text mycustomtype": true,
    "mycustomtype json": function( result ) {
      // Do stuff
      return newresult;
    }
  }
});

其他注意事項：

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

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

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

var menuId = $( "ul.nav" ).first().attr( "id" );
var request = $.ajax({
  url: "script.php",
  method: "POST",
  data: { id : menuId },
  dataType: "html"
});
 
request.done(function( msg ) {
  $( "#log" ).html( msg );
});
 
request.fail(function( jqXHR, textStatus ) {
  alert( "Request failed: " + textStatus );
});

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