阅读 36

jQuery.ajax()

jQuery.ajax( url [, settings ] )

说明: 执行一个异步的HTTP(Ajax)的请求。

jQuery.ajax( url [, settings ] )

url

  • 类型: String
  • 一个用来包含发送请求的URL字符串。

settings

  • 类型: PlainObject
  • 一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。可以使用$.ajaxSetup()设置任何默认参数。

jQuery.ajax( [settings ] )

settings

  • 类型: PlainObject
  • 一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。

accepts (默认: 取决于数据类型)

  • 类型: PlainObject
  • 内容类型发送请求头(Content-Type),用于通知服务器该请求需要接收何种类型的返回结果。如果accepts设置需要修改,推荐在$.ajaxSetup() 方法中设置一次。

beforeSend

  • 类型: Function( jqXHR jqXHR, PlainObject settings )
  • 请求发送前的回调函数,用来修改请求发送前jqXHR(在jQuery 1.4.x的中,XMLHttpRequest)对象,此功能用来设置自定义 HTTP 头信息,等等。该jqXHR和设置对象作为参数传递。这是一个Ajax事件 。在beforeSend函数中返回false将取消这个请求。从jQuery 1.5开始, beforeSend选项将被访问,不管请求的类型。

complete

  • 类型: Function( jqXHR jqXHR, String textStatus )
  • 请求完成后回调函数 (请求success 和 error之后均调用)。这个回调函数得到2个参数: jqXHR (在 jQuery 1.4.x中是 XMLHTTPRequest) 对象和一个描述请求状态的字符串("success", "notmodified", "error", "timeout", "abort", 或者 "parsererror") 。从jQuery 1.5开始, complete设置可以接受一个函数的数组。每个函数将被依次调用。这是一个Ajax事件 。

contents

  • 类型: PlainObject
  • 一个以"{字符串/正则表达式}"配对的对象,根据给定的内容类型,解析请求的返回结果。 (1.5新增)

contentType (默认: 'application/x-www-form-urlencoded; charset=UTF-8')

  • 类型: String
  • 发送信息至服务器时内容编码类型。默认值是"application/x-www-form-urlencoded; charset=UTF-8",适合大多数情况。如果你明确地传递了一个内容类型(Content-Type)给 $.ajax(),那么他必定会发送给服务器(即使没有数据要发送)。数据将总是使用UTF-8字符集传递给服务器;你必须在服务器端进行适当的解码。

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."(服务器内部错误)。 从jQuery 1.5开始, 在error设置可以接受函数组成的数组。每个函数将被依次调用。 注意:此处理程序在跨域脚本和JSONP形式的请求时不被调用。这是一个 Ajax Event。

success

  • 类型: Function( Object data, String textStatus, jqXHR jqXHR )
  • 请求成功后的回调函数。这个函数传递3个参数:从服务器返回的数据,并根据dataType参数进行处理后的数据,一个描述状态的字符串;还有 jqXHR(在jQuery 1.4.x前为XMLHttpRequest) 对象 。在jQuery 1.5, 成功设置可以接受一个函数数组。每个函数将被依次调用。这是一个 Ajax Event

timeout

  • 类型: Number
  • 设置请求超时时间(毫秒)。此设置将覆盖.ajaxSetup()里的全局设置。超时周期开始于.ajaxSetup() 里的全局设置。 超时周期开始于.ajax 访问成功的那个时间点;如果几个其他请求都在进步并且浏览器有没有可用的连接,它有可能在被发送前就超时了。在 jQuery 1.4.x 和前面的版本中, 如果请求超时,XMLHttpRequest对象是处于无效状态;访问任何对象的成员可能会抛出一个异常。只有在 Firefox 3.0+,script 和 JSONP请求在超时后不能被取消;该脚本将运行即使超时后到达。

url (默认: 当前页面地址)

  • 类型: String
  • 发送请求的地址。

jQuery 发送的所有 Ajax 请求,内部都会通过调用 $.ajax() 函数来实现。通常没有必要直接调用这个函数,可以使用几个已经封装的简便方法,如$.get()和.load()。如果你需要用到那些不常见的选项,那么, $.ajax()使用起来更灵活。

在简单地说, $.ajax()函数可以不带参数调用:

$.ajax();
复制代码

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

Callback Function Queues(回调函数)

beforeSend, error, dataFilter, success 和 complete接受的回调函数是在合适的时间调用。

从jQuery 1.5开始, fail , done ,和从jQuery 1.6开始的always回调钩子(hooks)采用先入先出队列管理。这意味着你可以为每个挂钩分配多个回调。见Deferred object methods ,这是实现内部的$.ajax()回调钩子(hooks)。

这里有$.ajax()提供的回调钩子 (hooks),如下:

  1. beforeSend 在发送请求之前调用,它接收jqXHR对象和settings作为参数对象。
  2. error 在请求出错时调用。如果请求失败,在它们的顺序依次登记。他们接受jqXHR ,字符串表示的错误类型,以及异常对象(如果有的话)。一些内置的错误会将 "abort", "timeout", "No Transport" 等字符串作为异常对象。
  3. dataFilter 在请求成功之后调用。传入返回的数据以及dataType参数的值。并且必须返回新的数据(可能是处理过的)传递给success回调函数。
  4. success 当请求成功并接收到返回数据之后调用。传入返回后的数据,以及包含成功代码的字符串和jqXHR对象。
  5. complete 请求完成时,无论是在失败或成功,它们按顺序依次执行回调。他们收到jqXHR对象,以及一个包含成功或错误代码。

Sending Data to the Server(发送数据到服务器)

默认情况下,Ajax请求使用GET方法。如果要使用POST方法,可以设定type参数值。这个选项也会影响 data 选项中的内容如何发送到服务器。POST数据将被发送到服务器使用UTF-8字符集,根据W3C XMLHttpRequest的标准。

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

参考资料

jQuery.ajax()

文章分类
前端
文章标签