第四周

jQuery.ajax()
Categories: Ajax > Low-Level Interface
jQuery.ajax( url, [ settings ] ) 返回: jqXHR
描述: 执行一个异步的HTTP（Ajax）的请求。

version added: 1.5jQuery.ajax( url, [ settings ] )
url一个用来包含发送请求的URL字符串。

settings一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。可以使用$.ajaxSetup()设置任何默认参数。看jQuery.ajax( settings )下所有设置的完整列表。

version added: 1.0jQuery.ajax( settings )
settings一个以"{键:值}"组成的AJAX 请求设置。所有选项都是可选的。可以使用$.ajaxSetup()设置任何默认参数。

acceptsMap
默认： 取决于数据类型
内容类型发送请求头，告诉服务器什么样的响应会接受返回。如果accepts设置需要修改，推荐在$.ajaxSetup()方法中做一次。

asyncBoolean
默认： true
默认设置下，所有请求均为异步请求（也就是说这是默认设置为true）。如果需要发送同步请求，请将此选项设置为 false。跨域请求和dataType: "jsonp"请求不支持同步操作。注意，同步请求将锁住浏览器，用户其它操作必须等待请求完成才可以执行。

beforeSend(jqXHR, settings)Function
发送请求前可修改 jqXHR（在jQuery 1.4.x的中，XMLHttpRequest） 对象的函数，如添加自定义 HTTP 头等。该jqXHR和设置作为参数传递的。这是一个Ajax事件 。beforeSend行数返回的false将取消该请求。在jQuery 1.5， beforeSend选项将被访问，不管请求的类型。

cacheBoolean
默认： true, dataType为"script"和"jsonp"时默认为false
如果设置为 false ，浏览器将不缓存此页面。

complete(jqXHR, textStatus)Function, Array
请求完成后回调函数 (请求成功或失败之后均调用)。这个回调函数得到2个参数： jqXHR (in jQuery 1.4.x, XMLHTTPRequest) 对象和一个描述成功请求类型的字符串(“success”, “notmodified”, “error”,“timeout”, or “parsererror”) 。在jQuery 1.5， complete设置可以接受一个函数的数组。每个函数将被依次调用。这是一个Ajax事件 。

contents(added 1.5)Map
一个以"{字符串:正则表达式}"配对的对象，用来确定jQuery将如何解析响应，给定其内容类型。

contentTypeString
默认: ‘application/x-www-form-urlencoded’
发送信息至服务器时内容编码类型。默认值是"application/x-www-form-urlencoded"，适合大多数情况。如果你明确地传递了一个content-type给 $.ajax() 那么他必定会发送给服务器（即使没有数据要发送）。数据将总是使用UTF-8字符集传递给服务器；你必须译码这适当的在服务器端。

contextObject
这个对象用于设置Ajax相关回调函数的上下文。也就是说，让回调函数内this指向这个对象（如果不设定这个参数，那么this就指向调用本次AJAX请求时传递的options参数）。比如指定一个DOM元素作为context参数，这样就设置了success回调函数的上下文为这个DOM元素。就像这样：

$.ajax({
url: “test.html”,
context: document.body,
success: function(){
$(this).addClass(“done”);
}
});converters(1.5新增)Map
默认： {"* text": window.String, “text html”: true, “text json”: jQuery.parseJSON, “text xml”: jQuery.parseXML}
一个数据类型对数据类型转换器的对象。每个转换器的值是一个函数，返回响应的转化值

crossDomain(1.5新增)
默认： 同域请求为false， 跨域请求为true
如果你想强制跨域请求（如JSONP形式）同一域，设置crossDomain为true。这使得例如，服务器端重定向到另一个域

dataObject, String
发送到服务器的数据。将自动转换为请求字符串格式。GET 请求中将附加在 URL 后。查看 processData 选项说明以禁止此自动转换。必须为"{键:值}"格式。如果为数组，jQuery 将自动为不同值对应同一个名称。如 {foo:[“bar1”, “bar2”]} 转换为 ‘&foo=bar1&foo=bar2’。 如果值是一个数组（ Array ）, jQuery将在 多个连续的值具有相同的键值的基础上建立的传统设置(下述)。

dataFilter(data, type)Function
一个函数被用来处理XMLHttpRequest的原始响应数据。这是一个预过滤功能，净化响应。您应该返回安全数据。提供data和type两个参数：data是Ajax返回的原始数据，type是调用jQuery.ajax时提供的dataType参数。函数返回的值将由jQuery进一步处理。

dataTypeString
默认: Intelligent Guess (xml, json, script, or html)
预期服务器返回的数据类型。如果不指定，jQuery 将自动根据 HTTP 包 MIME 信息来智能判断，比如XML MIME类型就被识别为XML。在1.4中，JSON就会生成一个JavaScript对象，而script则会执行这个脚本。随后服务器端返回的数据会根据这个值解析后，传递给回调函数。可用值:

“xml”: 返回 XML 文档，可用 jQuery 处理。.
“html”: 返回纯文本 HTML 信息；包含的script标签会在插入dom时执行。
“script”: 返回纯文本 JavaScript 代码。不会自动缓存结果。除非设置了"cache"参数。’’‘注意：’’'在远程请求时(不在同一个域下)，所有POST请求都将转为GET请求。(因为将使用DOM的script标签来加载)
“json”: 返回 JSON 数据 。1.4中，JSON就会生成一个JavaScript对象，而script则会执行这个脚本。
“jsonp”: JSONP 格式。使用JSONP 形式调用函数时，如 “myurl?callback=?” jQuery 将自动替换 ? 为正确的函数名，以执行回调函数。
“text”: 返回纯文本字符串。
多个空格分割的值:As of jQuery 1.5， jQuery可以从Content - Type头收到并转换一个您需要的数据类型。例如，如果你想要一个文本响应为XML处理，使用"text xml"数据类型。您也可以将一个JSONP的请求，以文本形式接受，并用jQuery以XML解析: “jsonp text xml”。同样地可以使用"jsonp xml"简写,将首先尝试从JSONP形式转换为XML,做不到这一点，并没有从文本，从JSONP形式转换为文本，然后到XML。
error(jqXHR, textStatus, errorThrown)Function
请求失败时调用此函数。有以下三个参数：jqXHR (在 jQuery 1.4.x中, XMLHttpRequest) 对象、描述发生的错误类型的一个字符串和捕获的异常对象。如果发生了错误，错误信息（第二个参数）除了得到null之外，还可能是"timeout", “error”, “abort” 和 “parsererror”。这是一个 Ajax Event。 在jQuery 1.5, 在error设置可以接受函数组成的数组。每个函数将被依次调用。 注意：此处理程序不被跨域脚本和JSONP形式的请求调用。

globalBoolean
默认: true
无论怎么样这个请求将触发全局AJAX事件处理程序。默认是true 。设置为 false 将不会触发全局 AJAX 事件，如 ajaxStart 或 ajaxStop 可用于控制不同的。这可以用来控制各种Ajax Events.

headers(1.5新增)Map
Default: {}
一个额外的"{键:值}"对映射到请求一起发送。此设置被设置之前beforeSend函数被调用;因此，消息头中的值设置可以在覆盖beforeSend函数范围内的任何设置。

ifModifiedBoolean
默认: false
仅在服务器数据改变时获取新数据。使用 HTTP 包 Last-Modified 头信息判断。在jQuery 1.4中，他也会检查服务器指定的’etag’来确定数据没有被修改过。

jsonpString
在一个jsonp请求中重写回调函数的名字。这个值用来替代在"callback=?“这种GET或POST请求中URL参数里的"callback"部分，比如{jsonp:‘onJsonPLoad’}会导致将"onJsonPLoad=?“传给服务器。在jQuery 1.5，，设置jsonp选项为false阻止了jQuery从加入”?callback"字符串的URL或试图使用”=?"转换。在这种情况下，你也应该明确设置jsonpCallback设置。例如, { jsonp: false, jsonpCallback: “callbackName” }

jsonpCallbackString, Function
为jsonp请求指定一个回调函数名。这个值将用来取代jQuery自动生成的随机函数名。这主要用来让jQuery生成度独特的函数名，这样管理请求更容易，也能方便地提供回调函数和错误处理。你也可以在想让浏览器缓存GET请求的时候，指定这个回调函数名。在jQuery 1.5，你也可以使用一个函数值该设置，在这种情况下jsonpCallback的值设置到该函数的返回值。

passwordString
用于响应HTTP访问认证请求的密码

processDataBoolean
默认: true
默认情况下，通过data选项传递进来的数据，如果是一个对象(技术上讲只要不是字符串)，都会处理转化成一个查询字符串，以配合默认内容类型 “application/x-www-form-urlencoded”。如果要发送 DOM 树信息或其它不希望转换的信息，请设置为 false。

scriptCharsetString
只有当请求时dataType为"jsonp"或"script"，并且type是"GET"才会用于强制修改charset。通常只在本地和远程的内容编码不同时使用。

statusCode(1.5新增)Map
默认: {}
一组数值的HTTP代码和函数对象，当响应时调用了相应的代码。例如，如果响应状态是404，将触发以下警报：

$.ajax({
statusCode: {404: function() {
alert(‘page not found’);
}
});如果请求成功，状态代码函数作为回调的成功相同的参数;如果在一个错误的结果，他们采取了相同的参数error回调。

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

timeoutNumber
设置请求超时时间（毫秒）。如果一个设置有$.ajaxSetup()，此设置将覆盖全局设置。例如，你可以使用这个属性来提供一个单一的请求比所有你所设置时间在一秒钟内的其他要求更长的超时。见$.ajaxSetup()全局超时。

traditionalBoolean
如果你想要用传统的方式来序列化数据，那么就设置为true。请参考工具分类下面的jQuery.param 方法.

typeString
默认: ‘GET’
请求方式 (“POST” 或 “GET”)， 默认为 “GET”。注意：其它 HTTP 请求方法，如 PUT 和 DELETE 也可以使用，但仅部分浏览器支持。

urlString
默认: 当前地址
发送请求的地址。

usernameString
于响应HTTP访问认证请求的用户名

xhrFunction
默认 ActiveXObject when available (IE), the XMLHttpRequest otherwise
需要返回一个XMLHttpRequest 对象。默认在IE下是ActiveXObject 而其他情况下是XMLHttpRequest 。用于重写或者提供一个增强的XMLHttpRequest 对象。这个参数在jQuery 1.3以前不可用。

Script和JSONP形式请求不受同源策略的限制。
Examples:
Example: 加载并执行一个 JS 文件。
$.ajax({
type: “GET”,
url: “test.js”,
dataType: “script”
});Example: 保存数据到服务器，成功时显示信息。
$.ajax({
type: “POST”,
url: “some.php”,
data: “name=John&location=Boston”,
success: function(msg){
alert( “Data Saved: " + msg );
}
});Example: 装入一个 HTML 网页最新版本。
$.ajax({
url: “test.html”,
cache: false,
success: function(html){
$(”#results").append(html);
}
});Example: 同步加载数据。发送请求时锁住浏览器。需要锁定用户交互操作时使用同步方式。
var html = $.ajax({
url: “some.php”,
async: false
}).responseText;Example: 发送 XML 数据至服务器。设置 processData 选项为 false，防止自动转换数据格式。
var xmlDocument = [create xml document];
$.ajax({
url: “page.php”,
processData: false,
data: xmlDocument,
success: handleResponse
});Example: 作为发送数据到服务器的ID，保存一些数据到服务器，并通知用户一旦它的完成。请注意，此用法 - 返回到一个变量的调用的结果 - 需要同步（阻塞）的要求！ （异步：假）
bodyContent = $.ajax({
url: “script.php”,
global: false,
type: “POST”,
data: ({id : this.getAttribute(‘id’)}),
dataType: “html”,
async:false,
success: function(msg){
alert(msg);
}
}
).responseText;