jQuery.ajax()| jqueryAPI 2.2 中文手册- AspRain.cn 致力于Web开发技术翻译整理

jQuery API 2.2.0

jQuery.ajax()

分类:Ajax > 底层接口

返回: jqXHR

jQuery.ajax( url [, settings ] )

描述:实施一个异步HTTP(Ajax)请求

加入于: 1.5
jQuery.ajax( url [, settings ] )
  • url
    类型:String
    一个字符串,它包含了要发送请求的URL。
  • settings
    类型:PlainObject
    一个用来配置Ajax请求的键值对。所有的设置项都是可选的。可以用$.ajaxSetup()设置任何选项的默认值。参见下面的jQuery.ajax( settings )以获得一个所有设置项的完整列表。
  • settings
    类型:PlainObject
    一个配置Ajax请求的键值对集合。所有的设置项都是可选的。可以用$.ajaxSetup()为任何选项设置默认值。
    • accepts (默认值:取决于DataType)
      类型:PlainObject
      在请求头中发送的内容类型,告诉浏览器你将在返回中接受哪种类型的响应。
    • async (默认值:true)
      类型:Boolean
      所有的请求默认都会异步发送(亦即,这个选项默认设置成true)如果你必须要用同步请求,请把这个选项设置成false。跨域请求以及dataType: "jsonp"请求不支持同步操作。注意,同步请求可能临时锁死浏览器,在请求激活期间禁用任何操作。自从jQuery 1.8,对jqXHR($.Deferred)使用async: false被建议弃用了;你必须使用success、error、complete回调函数选项代替相应的jqXHR对象的方法,比如说jqXHR.done()或者已被建议弃用的jqXHR.success()
    • beforeSend
      类型:FunctionjqXHR jqXHR, PlainObject settings )
      一个先于请求的回调函数,可以用来在请求发送之前修改jqXHR(在jQuery 1.4.x以前是XMLHTTPRequest)对象。使用它来发送自定义文件头,等等。传入jqXHR对象和setting对象,作为参数。这是一个Ajax事件。在beforeSend函数中返回false将取消请求。自从jQuery 1.5,无论哪种内容类型的请求,都将调用beforeSend选项。
    • cache (默认值:true,但是如果dataType是“script”和“jsonp”时,默认值是false)
      类型:Boolean
      如果设置为false,将强迫请求页不被浏览器缓存。注意:设置cachefalse只能对HEAD请求和GET请求正确起作用。它的作用方式是在GET参数后面追加一个_={timestamp}。对于别的类型的请求,不需要这个参数,除了在IE8中,当POST请求发送到一个URL时,已经用GET方法请求过了。
    • complete
      类型:FunctionjqXHR jqXHR, String textStatus )
      一个函数,在请求结束时调用它。该函数获得两个参数的参数:该jqXHR(在jQuery 1.4.x以前是XMLHTTPRequest)对象,以及一个对请求作分类的字符串("success""notmodified""nocontent""error""timeout""abort"或者"parseerror")。自从jQuery 1.5,complete设置可以接受一个函数的数组。将依次调用每个函数。这是一个Ajax事件。
    • contents
      类型:PlainObject
      一个字符串或正则表达式对对象,确定jQuery将如何解析这个响应,给定它的内容类型。(加入于:1.5
    • contentType (默认值:'application/x-www-form-urlencoded; charset=UTF-8')
      类型:Boolean or String
      在把数据发送到服务器时所使用的内容类型。默认值是"application/x-www-form-urlencoded; charset=UTF-8",它适用于大多数情况。如果你向$.ajax()显式传递一个content-type,则它总是会发送到服务器(哪怕没有发送数据)。自从jQuery 1.6,你可以传递false以告诉jQuery不要设置任何内容类型文件头。注意:W3C XMLHttpRequest规范文档规定charset(字符集)总是使用UTF-8;指定别的charset将不会强迫浏览器改变编码。注意:对于跨域请求,设置除了application/x-www-form-urlencodedmultipart/form-datatext/plain之外的内容类型,将触发浏览器向服务器发送一个preflight选项请求。
    • context
      类型:PlainObject
      该对象将是所有的Ajax相关的回调函数的上下文。默认情况下,该上下文将是一个对象,代表用在调用中的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
      一个对象,包含了“数据类型到数据类型”的转换器。每个转换器的值是一个函数,返回响应的转换值。(加入于:1.5
    • crossDomain (默认值:对于同域名请求,是false,对于跨域请求,是true)
      类型:Boolean
      如果你想在同域名中强迫使用跨域请求(比如说JSONP),请把crossDomain的值设置为true。这允许,比如说允许服务器端转向到别的域名。(加入于:1.5
    • data
      类型:PlainObject or String or Array
      要发送到服务器的数据。如果它还不是一个字符串,它会被转换成一个查询字符串。对于GET请求,它会被追加到url的末尾。参见processData选项以防止这种自动处理。对象必须是键值对。如果值是一个数组,jQuery会根据traditional选项的值,把带有同一个键的多个值序列化。
    • dataFilter
      类型:FunctionString data, String type ) => Anything
      一个函数,用它来处理XMLHttpRequest的未经加工响应数据。这是一个用来对响应进行无害化预筛选的函数。必须返回经无害化处理的数据。该函数接受两个参数:从服务器返回的未经加工的数据,以及dataType参数。
    • dataType (默认值:Intelligent Guess (xml, json, script, or html))
      类型:String
      你所期等的从服务器端返回的数据类型。如果没有指定它,jQuery将根据响应的MIME类型来推断它(一个XML MIME类型必须产生XML,在jQuery 1.4中,JSON MIME类型必须产生一个JavaScript对象,在jQuery 1.4中,script MIME类型必须必须执行脚本,除此之外任何东西都将作为字符串返回)可用的类型(以及传递作为你的success回调函数的第一个参数的结果)是:
      • "xml": 返回一个可以被jQuery处理的XML document。
      • "html": 返回HTML作为纯文本;包含的脚本标签在插入到DOM之时会被评估。
      • "script": 把响应估值为JavaScript,并以纯文本返回它。通过向URL追加一个查询字符串参数_=[TIMESTAMP]来禁用缓存,除非cache选项被设置为true注意:对于远程域名请求,这将把POST请求变成GET请求。
      • "json": 把响应评估为JSON,并返回一个JavaScript对象。跨域的“json”请求会转换成"jsonp",除非在该请求的请求选项中包含了jsonp: false。JSON会以严格的方式解析;任何格式糟糕的JSON都会被拒绝,并抛出一个解析错误。在jQuery 1.9版以后,任何空的响应都会被拒绝;服务器必须返回一个null{}响应来代替。(参阅json.org以了解更多关于正确的JSON格式的信息。)
      • "jsonp": 使用JSONP载入一个JSON块。在URL的末尾添加一个额外的"?callback=?"以指定回调函数。通过追加一个查询字符串参数"_=[TIMESTAMP]",可以禁用缓存,除非cache选项被设置为true
      • "text": 一个纯文本字符串。
      • 多个用空格隔开的值:自从jQuery 1.5,jQuery可以把一个来自它接收到的响应中的Content-Type头中的dataType转换成你想要的dataType。举个例子,如果你想让一个text响应被视为XML,请为dataType使用"text xml"。你还可以制作一个JSONP请求,虽然它是以文本的形式接收到的,但是jQuery可以把它翻译成XML:"jsonp text xml"类似地,一个简写的字符串,比如说"jsonp xml"将首先尝试把jsonp转换成XML,然后,如果失败,再把它从jsonp转换成text,然后再从text转换成xml。
    • error
      类型:FunctionjqXHR jqXHR, String textStatus, String errorThrown )
      一个函数,当请求失败时调用它。该函数接受三个参数:jqXHR(在jQuery 1.4以前的版本中是XMLHttpRequest)对象,一个描述发生的错误类型的字符串,以及一个可选的异常对象,如果其中这一发生了的话。第二个参数的可能值是(除了null之外)还有"timeout""error""abort"以及"parsererror"。在发生了一个HTTP错误的时候,errorThrown会接收到该HTTP状态的字面部分,比如说“Not Found”或者“Internal Server Error”。自从jQuery 1.5,error设置可以接受一个函数的数组。会依次调用每个函数。注意: 对于跨域script请求和跨域JSONP请求,不会调用该处理函数。这是一个Ajax事件。
    • global (默认值:true)
      类型:Boolean
      该请求是否触发了全局Ajax事件处理函数。默认值是true。把它设置为false就能阻止触发全局事件处理函数,比如说触发ajaxStart处理函数和ajaxStop处理函数。这可以用来控制多种不同的Ajax事件。
    • headers (默认值:{})
      类型:PlainObject
      一个额外文件头的键值对的对象,将使用XMLHttpRequest传播,与请求一起发送。总是会添加文件头X-Requested-With: XMLHttpRequest,但是可以在这里改变它的默认的XMLHttpRequest。还可以在beforeSend函数中覆盖设置这个文件头的值。(加入于:1.5
    • ifModified (默认值:false)
      类型:Boolean
      只有在本次请求与上次请求有所改变的情况下才允许让请求成功发送。这通过检查上一次修改的文件头来实现。默认值是false,忽略文件头。在jQuery 1.4中,这项技术还检查了服务器指定的“etag”,以捕获未修改的数据。
    • isLocal (默认值:取决于当前位置的协议)
      类型:Boolean
      允许当前环境被识别为“local”(例如,文件系统),哪怕jQuery默认不能这样识别它。以下协议当前会被识别为本地:file*-extension以及widget。如果需要修改isLocal设置,建议在$.ajaxSetup()方法中对它作一次性设置。(加入于:1.5.1
    • jsonp
      类型:String
      在一个JSONP请求中覆盖回调函数的名称。这个值将用来代替URL中的查询字符串的“callback=?”中的callback。所以{jsonp:'onJSONPLoad'}请导致'onJSONPLoad=?'发送到服务器。自从jQuery 1.5,把jsonp选项设置成false将防止jQuery在URL中添加“?callback”字符串,或者试图使用“=?”作为变形。在这种情况上,你还必须明确设置jsonpCallback选项。举个例子,{ jsonp: false, jsonpCallback: "callbackName" }
    • jsonpCallback
      类型:String or Function()
      指定用于JSONP请求的回调函数名。这个值将用来代替jQuery自动生成的随机名称。让jQuery生成一个独一无二的请求更可取,因为它更易于管理请求,并提供回调函数和错误处理。当你想启用GET请求的更好的浏览器缓存时,你可能想要指定回调函数。自从jQuery 1.5,你还可以为这个设置使用一个函数,那样的话,jsonpCallback的值会被设置为该函数返回的值。
    • method (默认值:'GET')
      类型:String
      用来发送请求的HTTP方法(例如,"POST""GET""PUT")(加入于:1.9.0
    • mimeType
      类型:String
      一个mime类型,用来覆盖XHR mime类型。(加入于:1.5.1
    • password
      类型:String
      一个密码,用在XMLHttpRequest中,以响应一个HTTP访问身份验证请求。
    • processData (默认值:true)
      类型:Boolean
      默认情况下,以一个对象(从技术上来说,除了字符串外的任何东西都是对象)的形式传递给data选项的数据将被处理,并转换成一个查询字符串,把默认的content-type固定为"application/x-www-form-urlencoded"。如果你想要发送一个DOMDocument,或者别的未经处理的数据,请把该选择设置为false
    • scriptCharset
      类型:String
      只有使用了“script”传播的时候(例如,用“jsonp”的跨域请求,或者使用了dataType:"script",type:"GET")才应用它。设置用在该请求中的在<script>元素标签上的元素属性charset。当本地网页的字符集与远程脚本的字符串不同的时候,需要使用它。
    • statusCode (默认值:{})
      类型:PlainObject

      数字HTTP代码,以及当响应具有对应的代码时执行的函数,所构成的对象。举个例子,以下代码将提醒响应状态是404:

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

      如果请求成功了,状态代码函数会取用和success回调函数同样的参数;如果以失败告终(包括3xx重定向),状态代码函数会取用和error回调函数同样的参数。

      (加入于:1.5
    • success
      类型:FunctionAnything data, String textStatus, jqXHR jqXHR )
      一个函数,在请求成功时调用它。该函数获得传入的三个参数:从服务器返回的数据,根据dataType参数或者dataFilter回调函数来格式化,如果指定了的话;一个字符串,描述了状态;还有jqXHR(在jQuery 1.4.x以前的版本中是XMLHttpRequest)对象。自从jQuery 1.6,success设置可以接受一个函数的数组。将依次调用每个函数。这是一个Ajax事件。
    • timeout
      类型:Number
      为请求设置超时(以毫秒计)。这可以覆盖在$.ajaxSetup()中所作的全局超时设置。超时阶段式制作$.ajax()调用的时间点开始算起;如果一些别的请求也在处理中,而且浏览器没有可用的连接,一个请求可能在发送之前就超时了。在jQuery 1.4.x及以前的版本中,如果请求超时,XMLHttpRequest对象将处于无效状态;访问对象的任何成员都将抛出一个异常。只有在Firefox 3.0中,script请求和jsonp请求不能由超时来取消;脚本将一直运行,哪怕它在超时阶段之后到达。
    • traditional
      类型:Boolean
      如果你想要使用传统样式的参数序列化,请把它设置为true
    • type (默认值:'GET')
      类型:String
      method的别名。如果你正在使用jQuery 1.9.0以前的版本,你必须使用type
    • url (默认值:The current page)
      类型:String
      一个字符串,它包含了要发送请求的URL。
    • username
      类型:String
      一个用户名,用在XMLHttpRequest中,以响应一个HTTP访问身份验证请求。
    • xhr (默认值:ActiveXObject when available (IE), the XMLHttpRequest otherwise)
      类型:Function()
      创建XMLHttpRequest对象的回调函数。当ActiveXObject可用时(在IE中),就用ActiveXObject对象,否则用XMLHttpRequest对象。提供你自己的实现器,以覆盖XMLHttpRequest,或者加强到工厂函数。
    • xhrFields
      类型:PlainObject

      一个设置在原生的XHR对象上的“字段名-字段值”对对象。举个例子,在需要的时候,你可以使用它,把withCredientials设置成true,以实现跨域请求。

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

      自从jQuery 1.5,该withCredientials属性不再传播到原生的XHR上,因此需要它的CORS请求会忽略这个标记。出于这个原因,我们建议使用jQuery 1.5.1以后的版本,你需要使用它。

      (加入于:1.5.1

$.ajax()函数成了所有jQuery发出Ajax请求的基础。通常并非一定要直接调用这个函数,因为很多较高级的替代方法,比如说 $.get().load()也是可用的,而且用起来更容易。然而,如果需要用到不常用的选项,可以灵活地使用$.ajax()

它的最简方式,$.ajax()函数可以不带参数地调用:

$.ajax();

注意:可以通过$.ajaxSetup()函数全局设置默认的设置项。

这个示例,没有任何任何选项,载入当前网页的内容,但是没有对结果做什么。要想使用这个结果,你可以在一个回调函数做点事。

jqXHR对象

自从jQuery 1.5版,由$.ajax()函数返回的jQuery XMLHttpRequest(jqXHR)对象,是浏览器的原生XMLHttpRequest对象的一个超级。举个例子,它包含了responseText属性和responseXML属性,还有getResponseHeader()方法。当传播机制不是XMLHttpRequest时(比如说,用于一个JSONP请求的script标签),则jqXHR对象尽可能地模仿了原生的XHR功能。

自从jQuery 1.5.1,jqXHR对象还包含了overrideMimeType()方法(它在jQuery 1.4.x中也是可用的,但是在jQuery 1.5中被临时删除了)。举个例子,.overrideMimeType()方法可以用在beforeSend()的回调函数中,以修改响应的content-type文件头:

$.ajax({
  url: "http://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 ) );
    }
  });

$.ajax()返回的jqXHR对象,自从jQuery 1.5以后,实现了Promise对象的接口,给它们一个Promise对象的所有的属性、方法和行为(参见Deferred object以获得更多信息)。这些方法要取用一个或更多的在该$.ajax()请求终止时调用的函数参数。这允许你在一个请求上分配多个回调函数,甚至在请求可能已经结束时分配架设函数。(如果请求已经结束,回调函数会立即被引发。)jqXHR对象可用的Promise方法包括:

  • jqXHR.done(function( data, textStatus, jqXHR ) {});对success回调函数选项的一个替代构造,.done()方法代替了这个建议弃用的jqXHR.success()方法。参见deferred.done()以了解编译器详情。
  • jqXHR.fail(function( jqXHR, textStatus, errorThrown ) {});
    对error回调函数选项的替代构造,.fail()方法替代了这个建议弃用的.error()方法。请参阅deferred.fail()以了解编译器详情。
  • jqXHR.always(function( data|jqXHR, textStatus, jqXHR|errorThrown ) { });
    对complete回调函数选项的替代构造,.always()方法替代了建议弃用的.complete()方法。
    在针对成功的请求的响应中,该函数的参数与.done()方法相同:data、textStatus以及该jqXHR对象。针对失败的请求,该函数的参数与.fail()方法相同:该jqXHR对象、textStatus以及errorThrown。请参阅deferred.always()以了解编译器详情。
  • jqXHR.then(function( data, textStatus, jqXHR ) {}, function( jqXHR, textStatus, errorThrown ) {});
    组合了.done()方法和.fail()方法的功能,允许(在jQuery 1.8版以后)操作底层的Promise对象。请参阅deferred.then()以了解编译器详情。

建议弃用提醒:回调函数jqXHR.success()jqXHR.error()jqXHR.complete()在jQuery 1.8中建议弃用了。要想在你的代码中准备好它们最终被删除,请使用jqXHR.done()jqXHR.fail()jqXHR.always()来代替。

// 在制作请求之后快速分配处理函数,
// 并记住针对该请求的jqXHR对象
var jqxhr = $.ajax( "example.php" )
  .done(function() {
    alert( "success" );
  })
  .fail(function() {
    alert( "error" );
  })
  .always(function() {
    alert( "complete" );
  });
 
// 在这里实施别的操作...
 
// 为上面的请求设置别的结束函数
jqxhr.always(function() {
  alert( "second complete" );
});

在所有回调函数内部的this引用是在$.ajax的设置项中传递给context的对象。如果没有指定contextthis会引用Ajax设置项本身。

为了与XMLHttpRequest向后兼容,一个jqXHR对象会显露出以下的属性和方法:

  • readyState
  • status
  • statusText
  • responseXML和/或responseText,分别是在底层请求用xml和/或text响应时
  • setRequestHeader(name, value)它与标准不同,通过用新值代替旧值,而不是把新值串联到旧值后面
  • getAllResponseHeaders()
  • getResponseHeader()
  • statusCode()
  • abort()

然而,没有提供onreadystatechange机制,因为donefailalwaysstatusCode已经覆盖了所有可能的需要。

回调函数队列

 beforeSend选项、error选项、dataFilter选项、success选项和complete选项都能接受回调函数,在特定的时候调用指定它们。

自从jQuery 1.5,回调函数faildone,自从jQuery 1.6,回调函数always勾子都是先进先出地管理队列,允许每个勾子对应不止一个回调函数。参见Deferred对象方法,它是针对这些$.ajax()回调函数勾子的内在实现。

$.ajax()函数提供的勾子包括以下这些:

  1. 可视情况调用执行beforeSend回调函数;它接收jqXHR对象以及settings对象用为参数。
  2. 如果请求失败了,会调用执行error回调函数。它接收jqXHR、一个表示错误类型的字符串,以及一个例外对象,如果有的话。一些内建的错误将提供一个字符串作为例外对象:"abort"、"timeout"、"No Transport"。
  3. dataFilter回调函数选项会在成功收到响应的数据时立即调用执行。它接收返回的数据,以及dataType的值,并且必须返回(可能更改过的)数据,以传给success函数。
  4. 如果请求成功了,就调用执行success回调函数。它接收返回的数据、一个包含success代码的字符串,以及jqXHR对象。
  5. Promise对象的回调函数——会按注册的顺序调用执行.done().fail().always().then()
  6. 当请求完成时,会视情况引发complete回调函数,无论请求是失败了还是成功了。它接收jqXHR对象,以及一个包含了success或error代码的字符串。

数据类型

对调用$.ajax()函数的响应的不同类型,在传递给success处理函数之前,要服从不同种类的预处理。预处理的类型默认由响应的Content-Type决定,但是可以使用dataType选项来显式设置。如果提供了dataType选项,响应的Content-Type文件头将会被无视。

可用的数据类型是texthtmlxmljsonjsonpscript

如果指定了text或者html,就不会发生预处理。数据直接传递给success处理函数,可以通过jqXHR对象的responseText属性来读取到。

如果指定了xml,就会在把参数传递给success处理函数之前,用jQuery.parseXML解析响应,作为一个XMLDocument。如果可以的话,会通过jqXHR对象的responseXML属性来制作该XML document。

如果指定了json,会在把参数传递给success处理函数之前,用jQuery.parseJSON来解析响应,转换成一个对象。如果可以的话,会通过jqXHR对象的responseJSON属性来制作这个经解析的JSON对象。

如果指定了script,$.ajax()将在从服务器上接收到数据之后,在把数据作为字符串传递给success处理函数之前,执行这个JavaScript。

如果指定了jsonp,$.ajax()会自动向URL追加一个查询字符串参数(默认是)callback=?。设置项中的jsonpjsonpCallback属性会传给$.ajax(),可以分别用这两个属性来设置查询字符串参数名和JSONP回调函数的名称。服务器将返回有效的JavaScript,把JSON响应传递给回调函数。$.ajax()在把响应中所包含的JSON对象传给success处理函数之前,将先执行返回的JavaScript,调用JSONP回调函数。

要想了解更多关于JSONP的信息,请参阅关于它的用法的早前发布的文章

把数据发送到服务器

默认情况下,Ajax请求是使用GET HTTP方法发送的。如果必须要用POST方法,可以通过给type选项设置值来指定该方法。该选项影响了data选项的内容如何发送到服务器。按照W3CXMLHttpRequest标准,总是会使用UTF08字符集把POST数据传输到服务器上。

data选项可以包含表单的一个查询字符串key1=value1&key2=value2,或者包含一个{key1: 'value1', key2: 'value2'}形式的对象。如果是后者,在发送它之前,会使用jQuery.param()把它转换成一个查询字符串。通过把processData设置成false,可以绕过这个处理过程。如果你想向服务器发送一个XML对象,这个处理过程可能是你不想要的。如果是这种情况,请把contentType选项从application/x-www-form-urlencoded改成更适合的MIME类型。

高级选项

.ajaxSend().ajaxError()和类似的方法可以注册一些Ajax全局处理函数,global选项设置成false防止了引发这些处理函数,当请求有可能触发这些处理函数时。这可能很有用,举个例子,如果该请求很频繁,而且很简短,可以用它抑制一个用.ajaxSend()实现的载入标识符。对于跨域script和jsonp请求,global选项会自动设置为false。请阅读下面这些方法的描述,以了解详情。

如果服务器在提供响应之前,会实施一个HTTP身份验证,是可以通过usernamepassword选项来发送用户名和密码。

Ajax请求是有时间限制的,从而会引起错误,并提供处理函数以获得一个更好的用户体验。请求超时,通常要么使用原来的默认值,要么使用$.ajaxSetup()设置一个全局默认值,而不是对特定的请求,用timeout覆盖默认值。

默认情况下,总是会发布请求,但是浏览器可能从缓存中提供结果。要想禁止使用缓存的结果,请把cache设置为false。如果提交的内容自上次请求之后,没有任何变化,要想让这样的请求报告成失败,请把ifMidified设置成true

scriptCharset允许为请求明确指定用于<sciript>标签(那是script或jsonp中的一种)的字符集。如果脚本和宿主网页有不同的字符集,这个选项会很有用。

Ajax这个词的第一个字母代表“asynchronous”,意味着操作发送在平行中,完成的顺序是不受保证的。$.ajax()async选项默认是true,表示在制作请求之后,代码可以继续执行。强烈不建议把这个选项设置为false(因此使这个调用不再异步),因为它会导致浏览器失去响应一小段时间。

$.ajax()函数返回它创建的XMLHttpRequest对象。通常地,jQuery会内部地处理这个对象的创建,但是一个使用xhr选项,可以指定一个用来操作它的自定义函数。返回的对象可以丢弃,但是确实提供了一个底层接口,以观察并操作这个请求。特别是,在对象上调用.abort(),将在它结束之前停止这个请求。

扩展Ajax

自从jQuery 1.5,jQuery的Ajax实现器包含了prefilterstransports,而且转换器允许你用一个很大的灵活性扩展Ajax。

使用转换器

$.ajax()转换器支持把数据类型映射到别的数据类型。然而,如果你想把自定义数据类型映射到一个已知的类型(例如json),你必须使用contents选项,在这种响应的Content-Type和实际类型之间添加通信:

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

该额外对象是必不可少的,因为响应的Content-Type以及数据类型不会是一个严格的“一对一”通信(正则表达式的结果)

要想把支持的类型(例如,textjson)转换成一个自定义类型,并回来,请使用另一个传递转换器:

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

现在上面的代码允许把传入的text转换成mycustomtype,然后再由mycustomtype转换成json

其它说明

  • 因为浏览器安全限制,很多Ajax请求要遵守同源策略;来自不同域名和子域名、端口或协议的请求不能成功地检索到。
  • Script请求和JSONP请求不需要遵同源策略限制。

示例

把一些数据保存到服务器,并要完成时提醒用户。

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

检索一个HTML网页的最后版本。

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

把一个xml作为数据发送到服务器。通过把processData选项设置为false,防止了自动把数据转换成字符串。

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

把一个id作为数据发送到服务器,把一些数据保存到服务器,并在完成时提醒用户。如果请求失败,也提醒用户。

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

载入并执行一个JavaScript文件。

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

如果网页上不能运行示例,请点击http://www.asprain.cn/jQueryAPI/jquery.ajax.htm查看示例。

如果你觉得本文档对你有用,欢迎给翻译作者支付宝打赏,支持翻译作者源源不断翻译更多有用的技术文档。