jQuery.ajax()

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

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

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

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

  • settings
    类型: PlainObject
    一组键值对，用于配置 Ajax 请求。所有设置都是可选的。任何选项都可以通过 $.ajaxSetup() 设置默认值。
    • accepts (默认: 取决于 dataType)
      类型: PlainObject
      一组键值对，将给定的 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 开始，使用 jqXHR ($.Deferred) 的 async: false 已弃用；您必须使用 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 中 POST 请求到已通过 GET 请求过的 URL。
    • 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
      类型: PlainObject
      一组字符串/正则表达式对，用于确定 jQuery 如何解析响应，具体取决于其内容类型。 (版本添加: 1.5)
    • contentType (默认: 'application/x-www-form-urlencoded; charset=UTF-8')
      类型: Boolean 或 String
      发送数据到服务器时，使用此内容类型。默认是 "application/x-www-form-urlencoded; charset=UTF-8"，这对于大多数情况都足够了。如果您显式地向 $.ajax() 传递了 content-type，那么它总是会发送到服务器（即使没有发送任何数据）。从 jQuery 1.6 开始，您可以传递 false 来告诉 jQuery 不设置任何 content type 头。注意: W3C XMLHttpRequest 规范规定 charset 始终为 UTF-8；指定其他 charset 不会强制浏览器更改编码。注意: 对于跨域请求，将 content type 设置为 application/x-www-form-urlencoded, multipart/form-data, 或 text/plain 以外的任何值都会触发浏览器向服务器发送一个预检 OPTIONS 请求。
    • context (上下文)
      类型: PlainObject
      此对象将是所有 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})
      类型: PlainObject
      一个包含 dataType 到 dataType 转换器的对象。每个转换器的值都是一个函数，它返回响应的转换值。 (版本添加: 1.5)
    • crossDomain (默认: 同域请求为 false，跨域请求为 true)
      类型: 布尔值
      如果您希望在同域上强制执行跨域请求（如 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 设置（如下所述）的值来序列化具有相同键的多个值。例如，使用默认的 traditional: false 设置，{ a: [1,2] } 将变成字符串 "a%5B%5D=1&a%5B%5D=2"。

      当 data 作为字符串传递时，它应该已经编码，符合 contentType 的正确编码，默认是 application/x-www-form-urlencoded。

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

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

      • "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 可以将从 Content-Type 头接收到的 dataType 转换为您需要的类型。例如，如果您希望将文本响应作为 XML 处理，请为 dataType 使用 "text xml"。您还可以发出一个 JSONP 请求，将其作为文本接收，然后由 jQuery 解释为 XML："jsonp text xml"。类似地，诸如 "jsonp xml" 这样的简写字符串将首先尝试从 jsonp 转换为 xml，如果失败，则从 jsonp 转换为 text，然后从 text 转换为 xml。
    • error
      类型: Function( jqXHR jqXHR, String textStatus, String errorThrown )
      如果请求失败时调用的函数。该函数接收三个参数：jqXHR (在 jQuery 1.4.x 中是 XMLHttpRequest) 对象，一个描述发生的错误类型的字符串，以及一个可选的异常对象（如果发生）。第二个参数的可能值（除了 null）是 "timeout", "error", "abort", 和 "parsererror"。当发生 HTTP 错误时，errorThrown 接收 HTTP 状态的文本部分，例如 "Not Found" 或 "Internal Server Error"。（在 HTTP/2 中可能为空字符串）从 jQuery 1.5 开始，error 设置可以接受一个函数数组。每个函数都将按顺序调用。注意: *此处理程序不用于跨域脚本和跨域 JSONP 请求。* 这是一个 Ajax 事件。
    • global (默认: true)
      类型: 布尔值
      是否为此请求触发全局 Ajax 事件处理程序。默认是 true。设置为 false 以阻止触发 ajaxStart 或 ajaxStop 等全局处理程序。这可以用于控制各种 Ajax 事件。
    • headers (默认: {})
      类型: PlainObject
      与使用 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
      类型: String 或 Boolean
      覆盖 JSONP 请求中的回调函数名称。此值将用于替换 URL 查询字符串中的 'callback'，而不是 'callback=?'。因此，{jsonp:'onJSONPLoad'} 将导致向服务器传递 'onJSONPLoad=?'。从 jQuery 1.5 开始，将 jsonp 选项设置为 false 可阻止 jQuery 向 URL 添加 "?callback" 字符串或尝试使用 "=?" 进行转换。在这种情况下，您还应该显式设置 jsonpCallback 设置。例如，{ jsonp: false, jsonpCallback: "callbackName" }。如果您不信任 Ajax 请求的目标，出于安全原因，请考虑将 jsonp 属性设置为 false。
    • jsonpCallback
      类型: String 或 Function()
      为 JSONP 请求指定回调函数名称。此值将用于替换 jQuery 自动生成的随机名称。最好让 jQuery 生成唯一的名称，因为它将使请求管理、提供回调和错误处理更加容易。当您想为 GET 请求启用更好的浏览器缓存时，可能需要指定回调。从 jQuery 1.5 开始，您也可以为此设置使用函数，在这种情况下，jsonpCallback 的值将设置为该函数的返回值。
    • method (默认: 'GET')
      类型: 字符串
      用于请求的 HTTP 方法（例如 "POST", "GET", "PUT"）。 (版本添加: 1.9)
    • mimeType
      类型: 字符串
      用于覆盖 XHR mime 类型的 mime 类型。 (版本添加: 1.5.1)
    • password
      类型: 字符串
      在响应 HTTP 访问身份验证请求时，用于 XMLHttpRequest 的密码。
    • processData (默认: true)
      类型: 布尔值
      默认情况下，传递给 data 选项的对象（严格来说，任何非字符串）将被处理并转换为查询字符串，符合默认内容类型 "application/x-www-form-urlencoded"。如果您想发送 DOMDocument 或其他未处理的数据，请将此选项设置为 false。
    • scriptAttrs
      类型: PlainObject
      定义一个对象，其中包含用于 "script" 或 "jsonp" 请求的附加属性。键表示属性的名称，值是属性的值。如果提供了此对象，它将强制使用脚本标签传输。例如，这可以用于设置 nonce, integrity, 或 crossorigin 属性，以满足内容安全策略要求。 (版本添加: 3.4)
    • scriptCharset
      类型: 字符串
      仅在 "script" 传输使用时适用。设置请求中使用的脚本标签上的 charset 属性。当本地页面的字符集与远程脚本的字符集不同时使用。或者，可以在 scriptAttrs 中指定 charset 属性，这也将确保使用 "script" 传输。
    • statusCode (默认: {})
      类型: PlainObject

      当响应具有相应代码时调用的数值 HTTP 状态码和函数的对象。例如，以下代码将在响应状态为 404 时触发警报

      1 2 3 4 5 6 7

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

      如果请求成功，状态码函数接收与 success 回调相同的参数；如果导致错误（包括重定向到另一个域的 3xx），则接收与 error 回调相同的参数。重定向到同一域的 3xx 由浏览器处理，不受 jQuery 控制。

      (版本添加: 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 请求无法通过超时取消；即使脚本在超时期限后到达，也会运行。
    • traditional
      类型: 布尔值
      如果您希望使用传统的 param 序列化样式，请将其设置为 true。
    • type (默认: 'GET')
      类型: 字符串
      method 的别名。如果您使用的是 jQuery 1.9.0 之前的版本，应使用 type。
    • url (默认: 当前页面)
      类型: 字符串
      一个字符串，包含请求发送到的 URL。
    • username
      类型: 字符串
      在响应 HTTP 访问身份验证请求时，用于 XMLHttpRequest 的用户名。
    • xhr (默认: 可用时为 ActiveXObject (IE)，否则为 XMLHttpRequest)
      类型：Function()
      创建 XMLHttpRequest 对象的 callback。默认为可用时为 ActiveXObject (IE)，否则为 XMLHttpRequest。重写此项可提供自己的 XMLHttpRequest 实现或增强工厂。
    • xhrFields
      类型: PlainObject

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