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