前言
在项目开发中,为了实现异步向服务端发起请求,最经常使用的就是jQuery.ajax方法了。刚开始需求比较简单,调用jQuery.ajax方法时要传的参数也就那几个常见的参数:url/data/dataType/type/cache/timeout。当时感觉这个接口使用起来很简单,直到最近项目中要实现一个发送 formData数据到服务端的需求时,我发现自己错了。。。。原来jQuery.ajax方法中除了我用过的那几个外,还有如此之多!!于是我决定要去jQuery官网好好看看都有哪些我不知道的参数!
参数解析
jQuery.ajax( )方法中的参数可以分为2类:
一类是ajax事件(local events)处理函数相关的参数:包括success/error/beforeSend/complete,这些参数都比较好理解,本文不会进行讨论,若有兴趣,请参考我另一篇文章《 jquery中ajax的相关事件汇总》;
另一类是与Ajax请求密切相关的参数,这是本文我想重点和大家解析的参数。
注意:这些参数都是可选参数,如果你没有自己手动设置这些参数,jquery 会使用这些参数的默认值。
1、url
默认值:当前页面的 url
类型:string(字符串)
含义:ajax 请求发送的目的地址(服务端地址)
2、type
默认值:’GET’
类型:string(字符串)
含义:请求的方式,可取值为”POST”, “GET”, “PUT”,”HEADER”等
3、data
默认值:无
类型:PlainObject or String or Array
含义:发送给服务端的数据。
默认情况下,jQuery会在发送之前将data处理为 query string 的格式如“key1=value1&key2=value2“(因为 contentType默认值为‘application/x-www-form-urlencoded;charset=UTF-8’);
若不想要 jQuery进行自动转换(将 data 转换为contentType所指定的格式),则可以通过设置processData=false ,这样 jQuery就不会对 data 进行格式处理了。
4、dataFilter
类型:function(data,type)
含义:对服务端返回的响应数据做进一步的过滤处理
5、accepts
默认值:dataType参数的值
类型:plainObject(简单对象)
含义:客户端告诉服务端自己能接收那些类型的响应数据
(如何使用???)
6、async
默认值:true
类型:boolean(布尔值)
含义:表明该 ajax 请求是异步还是同步。异步表示一旦发出这个请求
同步表示发出请求后,程序将暂停等待服务端响应,后面的代码将被阻塞。
直到接收到服务端响应后才继续执行后面的代码。
只需将 async 设置为 false,但由于此用法将阻塞浏览器,所以并不建议使用;
注意:跨域ajax请求和 dataType:jsonp的ajax请求中,不支持同步ajax请求
7、cache
默认值:true(但当 dataType为‘jsonp’或者‘script’时,cache默认值将为false)
类型:boolean(布尔值)
含义:当 cache 为 false 时,浏览器将不会缓存请求回来的 pages。当然若你请求的‘jsonp’或者‘script’时,浏览器将默认不缓存。
注意:只有对HEADER/GET类型的ajax请求设置 cache为 false 才有效。
(对于其他类型的ajax请求该参数是不需要的???)
8、contentType:
默认值:’application/x-www-form-urlencoded;charset=UTF-8’
类型:Boolean或String(布尔值/字符串)
含义:此参数用在客户端向服务端发送数据时(包括get、post)。contentType告诉了服务端‘客户端所发送数据的类型’,以帮助服务端解析数据。若你发送的数据不是contentType指定的类型数据,则 jQuery会自动将数据转换成contentType指定的类型(若要阻止jQuery进行自动转换,则设置 processData参数,见此文后面介绍)。
将contentType设置为 false,jQuery将不会在HTTP头部添加contentType字段。
注意:
1、若显式设置了该参数,则不管有没有数据,该 ajax 请求都会被发送。
2、客户端发送的数据charset只能是 UTF-8,即使你改成其他值,它还是会使用 UTF-8。
3、对于跨域请求,当contentType不是‘application/x-www-form-urlencoded’, ‘multipart/form-data’, or ‘text/plain’时,浏览器都会先发一个 OPTIONS 请求给服务端,然后才发我们要发的 Ajax 请求。
9、dataType
默认值:无
类型:string 字符串
含义:你想要接收的数据类型,若ajax 请求中显式设置了该参数,但服务端返回的数据类型不是dataType指定的类型时,jQuery将会自动将返回数据处理为 dataType的格式。默认情况下该参数没有设置,则 jQuery会根据 response 的 contentType Header来处理返回的数据(相当于将contenType作为 dataType) 。
dataType的值直接影响 success 成功回调函数的 data 参数:
dataType=’xml’:
jQuery会将返回数据处理为 XMLDocument 对象,此时data为 XMLDocument 对象 ,可以用 DOM API对 data直接操作;
通过 jqXHR.responseXML可以获取到;
dataType=’html’或‘text’:
jQuery不会对返回数据做任何处理,data 为纯文本,不能使用DOM API对 data直接操作;
通过 jqXHR.responseText可以获取到;
dataType=’json’:
jQuery会将返回数据处理为javascript对象, data 为javascript对象。若返回的数据为空将会报错,当无数据返回时应该返回null或者{};
通过 jqXHR.responseJSON可以获取到;
dataType=’script’:
jQuery不会对返回数据做任何处理,data 为纯文本。
但在 jQuery将数据传递给成功回调前,会先执行script 文本;
dataType=’jsonp’:
默认情况下(即没有显式设置 jsonp 参数时)jQuery会自动在请求 URL末尾添加“callback=?”;
服务端会返回 javascript 文本数据,jQuery会将其转换为 json 数据;
在将 json 数据传递给成功回调函数之前,jQuery会执行这些 javascript,同时也会调用 jsonpCallback回调函数;
你会发现:其实返回的数据类型就2大类:XML和文本(json 类型的数据也是字符串文本),所以ajax请求的响应只分为2种:responseText和responseXML
10、global
默认值:true
类型:boolean布尔值
含义:决定该ajax请求是否会触发ajax 的 global事件如 ajaxStop/ajaxStart。当 ajax请求为跨域的 script请求或 JSONP请求,则 global 自动被设置为 false;
11、headers
默认值:{}
类型:plainObject简单对象
含义:在请求header中添加额外的头部字段。
注意:该参数添加的头部字段可以在beforeSend方法中进行覆盖
12、ifModified
默认值:false
类型:boolean 布尔值
含义:当该参数为false时,jQuery将不会检查响应 header 的Last-Modified和etag字段;当为 true 时,jQuery则会检查这2个字段看数据是否有变化,有变化才触发 success 回调。
13、processData
默认值:true
类型:boolean 布尔值
含义:若此参数设置为true时,jQuery会将data参数的值处理为contentType参数所指定的格式类型。contentType的默认值为’application/x-www-form-urlencoded;charset=UTF-8’,所以当data参数值为 object 或 array 类型时,jQuery会将 data 数据自动转换为符合’application/x-www-form-urlencoded;charset=UTF-8’格式的数据(即 query string 类型)。当你要发送DOMDocument或者formData时,则应该将processData置为 false,以避免 jQuery对data做自动格式转换处理。
14、statusCode
默认值:{}
类型:plainObject
含义:定义了针对各个HTTP响应状态码的回调函数。实例如下:
$.ajax({
statusCode: {
404: function() {
alert( "page not found" );
}
}
});
15、timeout
默认值:无
类型: number (单位:毫秒)
含义:定义了 ajax 请求超时的时间。从ajax请求发送出去算起,经过了timeout指定的时间后,ajax 请求还未返回,则会触发 jquery ajax的 error 事件(原生的 XMLHttpRequest则会触发 ontimeout事件)。
16、context
默认值:ajax setting对象(是
.ajaxSetting和传给
.ajax的 setting 参数两者合并后的对象)
类型: 对象
含义:指代 ajax各种回调处理函数中的 this 。示例如下:
$.ajax({
url: "test.html",
context: document.body
}).done(function() {
$( this ).addClass( "done" );//此时的this指的是body对象
});
17、mimeType
默认值:无
类型: string
含义:功能与原生的 XMLHttpRequest.overrideMimeType( )一样,用来覆盖服务端所返回数据的 MIME 类型。比如你想将返回的数据当做‘text/xml’来处理和解析,即使服务端没有指定,则只需要将mimeType置为‘text/xml’。