jQuery.ajax()

描述: 执行异步 HTTP (Ajax) 请求。

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

  • url
    类型: 字符串
    包含发送请求的 URL 的字符串。
  • settings
    类型: 普通对象
    一组键值对，用于配置 Ajax 请求。所有设置都是可选的。可以使用 $.ajaxSetup() 为任何选项设置默认值。有关所有设置的完整列表，请参见下面的 jQuery.ajax( settings )。

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

  • settings
    类型: 普通对象
    一组键值对，用于配置 Ajax 请求。所有设置都是可选的。可以使用 $.ajaxSetup() 为任何选项设置默认值。
    • accepts (默认值: 取决于 dataType)
      类型: 普通对象
      一组键值对，将给定的 dataType 映射到其 MIME 类型，该类型将在 Accept 请求头中发送。此头告诉服务器它将接受哪种类型的响应。例如，以下代码定义了一个自定义类型 mycustomtype，它将与请求一起发送

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

      $.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' });

      注意: 您需要在 converters 中为该类型指定一个补充条目，才能使其正常工作。
    • async (默认值: true)
      类型: 布尔值
      默认情况下，所有请求都是异步发送的（即默认情况下设置为 true）。如果您需要同步请求，请将此选项设置为 false。跨域请求和 dataType: "jsonp" 请求不支持同步操作。请注意，同步请求可能会暂时锁定浏览器，在请求处于活动状态时禁用任何操作。从 jQuery 1.8 开始，使用 async: false 与 jqXHR（$.Deferred）已弃用；您必须使用 success/error/complete 回调选项，而不是 jqXHR 对象的相应方法，例如 jqXHR.done()。
    • beforeSend
      类型：Function( jqXHR jqXHR, PlainObject settings )
      一个预请求回调函数，可用于在发送 jqXHR（在 jQuery 1.4.x 中为 XMLHTTPRequest）对象之前修改它。使用它来设置自定义标头等。jqXHR 和 settings 对象作为参数传递。这是一个 Ajax 事件。在 beforeSend 函数中返回 false 将取消请求。从 jQuery 1.5 开始，beforeSend 选项将无论请求类型如何都会被调用。
    • cache（默认：true，dataType 为 'script' 和 'jsonp' 时为 false）
      类型: 布尔值
      如果设置为 false，它将强制请求的页面不被浏览器缓存。注意：将 cache 设置为 false 仅对 HEAD 和 GET 请求有效。它是通过在 GET 参数中追加 "_={timestamp}" 来实现的。对于其他类型的请求，该参数不需要，除非在 IE8 中，当对已通过 GET 请求的 URL 进行 POST 请求时。
    • complete
      类型：Function( jqXHR jqXHR, String textStatus )
      请求完成后（在 success 和 error 回调执行后）要调用的函数。该函数传递两个参数：jqXHR（在 jQuery 1.4.x 中为 XMLHTTPRequest）对象和一个字符串，用于对请求的状态进行分类（"success"、"notmodified"、"nocontent"、"error"、"timeout"、"abort" 或 "parsererror"）。从 jQuery 1.5 开始，complete 设置可以接受一个函数数组。每个函数将依次被调用。这是一个 Ajax 事件。
    • contents
      类型: 普通对象
      一个字符串/正则表达式对的集合，用于确定 jQuery 如何解析响应，具体取决于其内容类型。（版本添加：1.5）
    • contentType（默认值：'application/x-www-form-urlencoded; charset=UTF-8'）
      类型：布尔值 或 字符串
      向服务器发送数据时使用的内容类型。默认值为 "application/x-www-form-urlencoded; charset=UTF-8"，适用于大多数情况。如果您在 $.ajax() 中显式传递内容类型，则它始终会发送到服务器（即使没有发送数据）。从 jQuery 1.6 开始，您可以传递 false 来告诉 jQuery 不要设置任何内容类型标头。注意：W3C XMLHttpRequest 规范规定字符集始终为 UTF-8；指定其他字符集不会强制浏览器更改编码。注意：对于跨域请求，将内容类型设置为除 application/x-www-form-urlencoded、multipart/form-data 或 text/plain 之外的任何内容，将触发浏览器向服务器发送预检 OPTIONS 请求。
    • context
      类型: 普通对象
      此对象将成为所有与 Ajax 相关的回调的上下文。默认情况下，上下文是一个表示调用中使用的 Ajax 设置的对象（$.ajaxSettings 与传递给 $.ajax 的设置合并）。例如，将 DOM 元素指定为上下文将使其成为请求的 complete 回调的上下文，如下所示

      1 2 3 4 5 6

      $.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}）
      类型: 普通对象
      包含数据类型到数据类型转换器的对象。每个转换器的值都是一个函数，它返回响应的转换后的值。（添加版本：1.5）
    • crossDomain（默认值：对于同域请求为 false，对于跨域请求为 true）
      类型: 布尔值
      如果您希望在同一域上强制执行跨域请求（例如 JSONP），请将 crossDomain 的值设置为 true。这允许例如服务器端重定向到另一个域。（添加版本：1.5）
    • data
      类型：普通对象 或 字符串 或 数组

      要发送到服务器的数据。如果 HTTP 方法是不能有实体主体的方法，例如 GET，则 data 会附加到 URL。

      当 data 是一个对象时，jQuery 会从对象的键值对生成数据字符串，除非 processData 选项设置为 false。例如，{ a: "bc", d: "e,f" } 会转换为字符串 "a=bc&d=e%2Cf"。如果值为数组，jQuery 会根据 traditional 设置的值（如下所述）序列化具有相同键的多个值。例如，{ a: [1,2] } 会使用默认的 traditional: false 设置变为字符串 "a%5B%5D=1&a%5B%5D=2"。

      当 data 作为字符串传递时，它应该已经使用正确的编码对 contentType 进行编码，默认情况下为 application/x-www-form-urlencoded。

      在使用 dataType: "json" 或 dataType: "jsonp" 的请求中，如果 URL 或查询字符串中的任何位置包含双问号 (??) 或查询字符串中包含单个问号 (?)，它将被替换为 jQuery 生成的唯一值，该值对于页面上的每个库副本都是唯一的 (例如 jQuery21406515378922229067_1479880736745)。

    • dataFilter
      类型：函数( 字符串 data, 字符串 type ) => 任何
      用于处理 XMLHttpRequest 的原始响应数据的函数。这是一个预过滤函数，用于清理响应。您应该返回清理后的数据。该函数接受两个参数：从服务器返回的原始数据和 'dataType' 参数。
    • dataType (默认值：智能猜测 (xml、json、script 或 html))
      类型: 字符串
      您期望从服务器接收的数据类型。如果没有指定，jQuery 将尝试根据响应的 MIME 类型推断它 (XML MIME 类型将产生 XML，在 1.4 中 JSON 将产生 JavaScript 对象，在 1.4 中 script 将执行脚本，其他任何内容将作为字符串返回)。可用的类型 (以及作为第一个参数传递给您的成功回调的结果) 是

      • "xml"：返回一个可以通过 jQuery 处理的 XML 文档。
      • "html"：返回纯文本形式的 HTML；包含的脚本标签在插入 DOM 时将被评估。
      • "script"：将响应评估为 JavaScript 并将其作为纯文本返回。通过将查询字符串参数 _=[TIMESTAMP] 附加到 URL 来禁用缓存，除非 cache 选项设置为 true。注意：这将把远程域请求的 POST 转换为 GET。在 jQuery 3.5.0 之前，具有脚本 Content-Type 的不成功的 HTTP 响应仍然会被执行。
      • "json"：将响应评估为 JSON 并返回一个 JavaScript 对象。跨域 "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 可以将 dataType 从它在 Content-Type 标头中接收到的内容转换为您需要的类型。例如，如果您希望文本响应被视为 XML，请使用 "text xml" 作为 dataType。您还可以进行 JSONP 请求，将其接收为文本，并由 jQuery 解释为 XML："jsonp text xml"。类似地，"jsonp xml" 这样的简写字符串将首先尝试从 jsonp 转换为 xml，如果失败，则从 jsonp 转换为文本，然后从文本转换为 xml。
    • error
      类型：函数( jqXHR jqXHR, 字符串 textStatus, 字符串 errorThrown )
      如果请求失败，将调用此函数。该函数接收三个参数：jqXHR（在 jQuery 1.4.x 中为 XMLHttpRequest）对象、描述发生的错误类型的字符串以及可选的异常对象（如果有）。第二个参数的可能值（除了 null）是 "timeout"、"error"、"abort" 和 "parsererror"。当发生 HTTP 错误时，errorThrown 将接收 HTTP 状态的文本部分，例如“未找到”或“内部服务器错误”。（在 HTTP/2 中，它可能为空字符串）从 jQuery 1.5 开始，error 设置可以接受一个函数数组。每个函数将依次被调用。注意：此处理程序不会针对跨域脚本和跨域 JSONP 请求调用。 这是一个 Ajax 事件。
    • global（默认值：true）
      类型: 布尔值
      是否为该请求触发全局 Ajax 事件处理程序。默认值为 true。设置为 false 以阻止触发全局处理程序（如 ajaxStart 或 ajaxStop）。这可用于控制各种 Ajax 事件。
    • headers（默认值：{}）
      类型: 普通对象
      使用 XMLHttpRequest 传输发送请求时，要附加的额外标头键/值对的对象。标头 X-Requested-With: XMLHttpRequest 始终添加，但其默认 XMLHttpRequest 值可以在此处更改。headers 设置中的值也可以在 beforeSend 函数中覆盖。（添加版本：1.5）
    • ifModified（默认值：false）
      类型: 布尔值
      仅当响应自上次请求以来已更改时，才允许请求成功。这是通过检查 Last-Modified 标头来完成的。默认值为 false，忽略标头。在 jQuery 1.4 中，此技术还检查服务器指定的“etag”以捕获未修改的数据。
    • isLocal（默认值：取决于当前位置协议）
      类型: 布尔值
      允许当前环境被识别为“本地”（例如文件系统），即使 jQuery 默认情况下不将其识别为本地。目前以下协议被识别为本地：file、*-extension 和 widget。如果 isLocal 设置需要修改，建议在 $.ajaxSetup() 方法中进行一次修改。 (版本添加：1.5.1)
    • jsonp
      类型：字符串 或 布尔值
      覆盖 JSONP 请求中的回调函数名称。此值将用于 URL 查询字符串中的“callback=?”部分，而不是“callback”。因此，{jsonp:'onJSONPLoad'} 将导致 'onJSONPLoad=?' 传递给服务器。从 jQuery 1.5 开始，将 jsonp 选项设置为 false 将阻止 jQuery 将“?callback”字符串添加到 URL 或尝试使用“=?”进行转换。在这种情况下，您还应该显式设置 jsonpCallback 设置。例如，{ jsonp: false, jsonpCallback: "callbackName" }。如果您不信任 Ajax 请求的目标，出于安全原因，请考虑将 jsonp 属性设置为 false。
    • jsonpCallback
      类型：字符串 或 函数()
      指定 JSONP 请求的回调函数名称。此值将用于代替 jQuery 自动生成的随机名称。最好让 jQuery 生成一个唯一的名称，因为它将使管理请求以及提供回调和错误处理变得更容易。当您想要启用对 GET 请求的更好的浏览器缓存时，您可能需要指定回调。从 jQuery 1.5 开始，您也可以为此设置使用函数，在这种情况下，jsonpCallback 的值将设置为该函数的返回值。
    • method（默认：'GET'）
      类型: 字符串
      用于请求的 HTTP 方法（例如 "POST"、"GET"、"PUT"）。 (版本添加：1.9)
    • mimeType
      类型: 字符串
      用于覆盖 XHR 类型的 MIME 类型。 (版本添加：1.5.1)
    • password
      类型: 字符串
      用于响应 HTTP 访问身份验证请求的 XMLHttpRequest 的密码。
    • processData（默认：true）
      类型: 布尔值
      默认情况下，传递到 data 选项中的对象（技术上来说，任何不是字符串的东西）将被处理并转换为查询字符串，适合默认的 content-type“application/x-www-form-urlencoded”。如果您想发送 DOMDocument 或其他未处理的数据，请将此选项设置为 false。
    • scriptAttrs
      类型: 普通对象
      定义一个包含附加属性的对象，用于 "script" 或 "jsonp" 请求。键表示属性的名称，值表示属性的值。如果提供了此对象，它将强制使用脚本标签传输。例如，这可用于设置 nonce、integrity 或 crossorigin 属性以满足内容安全策略要求。 (版本添加: 3.4)
    • scriptCharset
      类型: 字符串
      仅在使用 "script" 传输时适用。设置请求中使用的脚本标签上的 charset 属性。当本地页面的字符集与远程脚本上的字符集不同时使用。或者，可以在 scriptAttrs 中指定 charset 属性，这也会确保使用 "script" 传输。
    • statusCode (默认: {})
      类型: 普通对象

      一个包含数字 HTTP 代码和函数的对象，当响应具有相应的代码时调用这些函数。例如，以下代码将在响应状态为 404 时发出警报

      1 2 3 4 5 6 7

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

      如果请求成功，状态代码函数将接收与成功回调相同的参数；如果导致错误（包括 3xx 重定向），它们将接收与 error 回调相同的参数。

      (版本添加: 1.5)
    • success
      类型: Function( Anything data, String textStatus, jqXHR jqXHR )
      如果请求成功，则调用此函数。该函数将传递三个参数：从服务器返回的数据，根据 dataType 参数或 dataFilter 回调函数（如果指定）进行格式化；描述状态的字符串；以及 jqXHR（在 jQuery 1.4.x 中为 XMLHttpRequest）对象。从 jQuery 1.5 开始，success 设置可以接受一个函数数组。每个函数将依次调用。 这是一个 Ajax 事件。
    • timeout
      类型: Number
      为请求设置超时时间（以毫秒为单位）。值为 0 表示没有超时。这将覆盖使用 $.ajaxSetup() 设置的任何全局超时时间。超时时间从调用 $.ajax 的那一刻开始计算；如果还有其他请求正在进行，并且浏览器没有可用连接，则请求可能会在发送之前超时。在 jQuery 1.4.x 及更低版本中，如果请求超时，XMLHttpRequest 对象将处于无效状态；访问任何对象成员可能会抛出异常。仅在 Firefox 3.0+ 中，脚本和 JSONP 请求无法通过超时取消；即使脚本在超时时间后到达，也会运行。
    • 传统
      类型: 布尔值
      如果要使用传统的 param 序列化 样式，请将其设置为 true。
    • type（默认值：'GET'）
      类型: 字符串
      method 的别名。如果您使用的是 jQuery 1.9.0 之前的版本，则应使用 type。
    • url（默认值：当前页面）
      类型: 字符串
      包含发送请求的 URL 的字符串。
    • 用户名
      类型: 字符串
      用于响应 HTTP 访问身份验证请求的 XMLHttpRequest 的用户名。
    • xhr（默认值：如果可用，则为 ActiveXObject（IE），否则为 XMLHttpRequest）
      类型：Function()
      用于创建 XMLHttpRequest 对象的回调函数。默认情况下，如果可用，则为 ActiveXObject（IE），否则为 XMLHttpRequest。覆盖此函数以提供您自己的 XMLHttpRequest 实现或对工厂进行增强。
    • xhrFields
      类型: 普通对象

      要在本机 XHR 对象上设置的 fieldName-fieldValue 对的集合。例如，您可以使用它将 withCredentials 设置为 true，以便在需要时进行跨域请求。

      1 2 3 4 5 6

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