返回值:XMLHttpRequestjQuery.ajax(settings)

执行异步 HTTP (Ajax) 请求。

jQuery 发送的所有 Ajax 请求,内部都会通过调用 $.ajax() 函数来实现。通常没有必要直接调用这个函数,有几个简单易用的封装可以使用,比如 $.get().load()。如果你需要使用几个不常用的选项,那么 $.ajax() 可以提供更高的灵活性。

最简单的情况下, $.ajax() 可以不带任何参数直接使用:

$.ajax();

注意: 所有选项的默认值都可以通过 $.ajaxSetup() 函数来全局设置。

上面这个例子中,我们没用使用任何选项,于是默认会载入当前页面的内容,但载入的结果是无法使用的。如果想要进一步处理先前载入的数据,我们就需要使用回调函数来操作了。

回调函数

beforeSend, error, dataFilter, successcomplete 等选项都可以接受一个函数,这个函数会在适当的时机执行。这些函数中的 this 会始终指向传递给 $.ajax 函数的选项中, context 属性所指向的对象。如果没有设置 context ,则 context 会指向传给 $.ajax 函数的选项本身。有些类型的 Ajax 请求,比如 JSONP 和跨域的 GET 请求,本身不使用 XHR,所以在这种情况下,传给回调函数的 XMLHttpRequest 参数就是 undefined 了。

  1. beforeSend 会在发送请求之前调用,并且传入一个 XMLHttpRequest 对象作为参数。
  2. error 会在请求失败时调用。他会传入 XMLHttpRequest,描述错误类型的字符串,以及一个异常对象(如果有的话)
  3. dataFilter 会在请求成功之后调用。他会传入请求到的数据以及 dataType 参数的值。并且必须返回一个新的数据(可以是处理过的),这个数据将传递给 success 回调函数做进一步处理。
  4. success 会在请求成功之后调用。他会传入请求到的数据,包含成功代码的字符串,以及 XMLHttpRequest 对象。
  5. complete 无论请求成败与否,他都会在请求结束后调用。他会传入 XMLHttpRequest 对象,以及一个包含成功或失败代码的字符串

如果想直接使用返回的 HTML,可以给 success 添加如下的处理函数:

$.ajax({
  url: 'ajax/test.html',
  success: function(data) {
    $('.result').html(data);
    alert('Load was performed.');
  }
});

如此简单的例子,还可以用更优雅的方式来替代: .load()$.get()

数据类型

$.ajax() 函数依赖服务器提供的信息来处理返回的数据。如果服务器报告说返回的数据是XML,那么返回的结果就可以用普通的XML方法或者jQuery的选择器来遍历。如果检测到到其他类型,比如HTML,则数据就以文本形式来对待。

通过设定 dataType 选项,可以指定成其他不同数据类型. 除了 xml, dataType 还可以是 html, json, jsonp, script, 火 text.

其中, textxml 类型返回的数据不会经过处理。数据仅仅简单的将 XMLHttpRequestresponseTextresponseXML 属性传递给 success 回调函数。

注意: 我们必须确保服务器端报告的 MIME 类型与我们选择的 dataType 所匹配。比如说,选择 XML 的话,服务器端就必须声明 text/xmlapplication/xml

如果指定为 html 类型,任何内嵌的JavaScript都会在HTML作为一个字符串返回之前执行。类似的,指定 script 类型的话,也会先执行服务器端生成 JavaScript 脚本,然后再把脚本作为一个文本数据返回。

如果指定为 json 类型,则会把获取到的数据作为一个JavaScript对象来解析,并且把构建好的对象作为结果返回。为了实现这个目的,首先尝试使用 JSON.parse()。如果浏览器不支持,则使用一个Functionconstructor。格式有误的 JSON 数据会抛出一个错误,详见 json.org 。JSON数据是一种能很方便通过JavaScript解析的结构化数据。如果获取的数据文件存放在远程服务器上(域名不同,也就是跨域获取数据),则需要使用jsonp类型来代替。

使用 jsonp 类型的话,会创建一个查询字符串参数 callback=? ,这个参数会加在请求的URL后面。服务器端应当在JSON数据前加上回调函数名,以便完成一个有效的JSONP请求。如果要指定回调函数的参数名来取代默认的callback,可以通过设置 $.ajax()jsonp 参数。

注意, JSONP是JSON格式的扩展。他要求一些服务器端的代码来检测并处理查询字符串参数。更多信息可以参阅 最早关于 JSONP 的文章.

当数据需要从远端服务器上获得时(这只可能是用了 scriptjsonp 数据类型),这个操作实际上是使用了 <script> 标签,而并非 XMLHttpRequest 对象。所以这种情况下,XMLHttpRequest 对象既不会作为 $.ajax() 函数的返回值,也不会传递给任何回调函数(比如 beforeSend)。

发送数据到服务器

默认情况下,Ajax请求使用GET方法。如果要使用POST方法,可以设定 type 选项。这个选项也会影响 data 选项中的内容如何发送到服务器。按照 W3C XMLHTTPRequest 的标准,POST 的数据始终是用 UTF-8 字符集传输的。

data 选项既可以包含一个查询字符串,比如 key1=value1&key2=value2也可以是一个映射,比如 {key1: 'value1', key2: 'value2'}。如果使用了后者的形式,则数据在发送给服务器前会被 jQuery.param() 转换成查询字符串。这个处理过程也可以通过设置 processDatafalse 来回避。比如我们希望发送一个 XML 对象给服务器时,这种处理就可能不合适了。同时在这种情况下,我们还应当设置 contentType 选项,使用其他合适的 MIME 类型,取代默认的 application/x-www-form-urlencoded

高级选项

global 选项用于在 Ajax 请求时,阻止响应全局注册的 Ajax 事件回调函数,比如 .ajaxSend(), .ajaxError() ,以及其他类似的方法。这在有些时候很有用,比如发送的请求非常频繁且简短的时候,就可以禁用 .ajaxSend() 里设置的载入等待指示器。更多关于这些方法的详细信息,请参阅下面的内容。

如果服务器需要HTTP认证,可以使用用户名和密码可以通过 usernamepassword 选项来设置。

Ajax请求是限时的,所以错误警告被捕获并处理后,可以用来提升用户体验。请求超时这个参数通常就保留其默认值,或者就通过$.ajaxSetup()来全局设定,很少为特定的请求重新设置 timeout 选项。

默认情况下,请求总会被发出去的,但浏览器有可能从他的缓存中调取数据。要禁止使用缓存的结果,可以设置 cache 参数为 false 。如果希望判断数据自从上次请求后是否更改过,如果没有更改过就报告请求失败的话,可以设置 ifModified 参数为 true

scriptCharset 参数允许给 <script> 标签的请求设定一个特定的字符集,通常用户 用于 script 或者 script 的数据。当脚本和页面字符集不同时,这特别好用。

Ajax 的第一个字母是 "asynchronous" 的开头字母,这意味着所有的操作都是并行的,完成的顺序没有前后关系。$.ajax()async 选项默认是 true,这意味着在请求开始后,其他代码依然能够执行。强烈不建议把这个选项设置成false(意味着所有的请求都不再是异步的了),这会导致浏览器显得反应迟钝。

$.ajax() 函数返回他创建的 XMLHttpRequest对象。通常jQuery只在内部处理并创建这个对象,但用户也可以通过 xhr 选项来传递一个自己创建的xhr对象。返回的对象通常已经被丢弃了,但依然提供一个底层接口来观察和操控请求。比如说,调用对象上的 .abort() 可以在请求完成前中止请求。

示例:

加载并执行一个 JavaScript 文件。

jQuery 代码:
$.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });

示例:

保存数据到服务器,成功时显示信息。

jQuery 代码:
$.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

示例:

装入一个 HTML 网页最新版本。

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

示例:

同步加载数据。发送请求时锁住浏览器。当需要使用同步方式加载数据时,最好通过其他方式锁住用户的交互行为。

jQuery 代码:
var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;

示例:

发送 XML 数据至服务器。设置 processData 选项为 false,防止自动转换数据格式。

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

示例:

发送一个 id 数据到服务器,并在成功后通知用户。注意这种用法——把返回的数据装入一个变量中——必须使用同步请求(即锁住脚本进程)!(async:false)

jQuery 代码:
bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      async:false,
      success: function(msg){
         alert(msg);
      }
   }
).responseText;