$.ajax() 参数详解

今天遇到一个ajax请求，跨域未带cookie的问题。解决方法是在ajax请求参数中加上

xhrFields: {
   withCredentials: true
},

下面对ajax中的所有参数做一个收集：https://codeplayer.vip/p/j7ss9

• accepts: object 默认值：取决于dataType属性。

  发送的内容类型请求头，用于告诉服务器——浏览器可以接收服务器返回何种类型的响应。

• async: asyncBoolean 默认值：true。

  指示是否是异步请求。同步请求将锁定浏览器，直到获取到远程数据后才能执行其他操作。

• beforeSend: Function 指定在请求发送前需要执行的回调函数。

  该函数还有两个参数：其一是jqXHR对象，其二是当前settings对象。这是一个Ajax事件，如果该函数返回false，将取消本次ajax请求。

• cache: Boolean 默认值：true(dataType为'script'或'jsonp'时，则默认为false)。

  指示是否缓存URL请求。如果设为false将强制浏览器不缓存当前URL请求。该参数只对HEAD、GET请求有效(POST请求本身就不会缓存)。

• complete:Function/Array类型 指定请求完成(无论成功或失败)后需要执行的回调函数。该函数还有两个参数：一个是jqXHR对象，一个是表示请求状态的字符串('success'、 'notmodified'、 'error'、 'timeout'、 'abort'或'parsererror')。这是一个Ajax事件。

  从jQuery 1.5开始，该属性值可以是数组形式的多个函数，每个函数都将被回调执行。

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

• contentType:String类型 默认值：'application/x-www-form-urlencoded; charset=UTF-8'。

  使用指定的内容编码类型将数据发送给服务器。W3C的XMLHttpRequest规范规定charset始终是UTF-8，你如果将其改为其他字符集，也无法强制浏览器更改字符编码。

• context:Object类型 用于设置Ajax相关回调函数的上下文对象(也就是函数内的this指针)。

• converters:Object类型 1.5 新增 ; 默认值：{'* text': window.String, 'text html': true, 'text json': jQuery.parseJSON, 'text xml': jQuery.parseXML}。

  一个数据类型转换器。每个转换器的值都是一个函数，用于返回响应转化后的值。

• crossDomain:Boolean类型 1.5 新增 ; 默认值：同域请求为false，跨域请求为true。

  指示是否是跨域请求。如果你想在同一域中强制跨域请求(如JSONP形式)，请设置为true。例如，这允许服务器端重定向到另一个域。

• data:任意类型 发送到服务器的数据，它将被自动转为字符串类型。如果是GET请求，它将被附加到URL后面。

• dataFilter:Function类型 指定处理响应的原始数据的回调函数。

  该函数还有两个参数：其一表示响应的原始数据的字符串，其二是dataType属性字符串。

• dataType:String类型 默认值：jQuery智能猜测，猜测范围(xml、 json、 script或html)

  指定返回的数据类型。该属性值可以为：

  • 'xml' :返回XML文档，可使用jQuery进行处理。
  • 'html': 返回HTML字符串。
  • 'script': 返回JavaScript代码。不会自动缓存结果。除非设置了cache参数。注意：在远程请求时(不在同一个域下)，所有POST请求都将转为GET请求。(因为将使用DOM的script标签来加载)
  • 'json': 返回JSON数据。JSON数据将使用严格的语法进行解析(属性名必须加双引号，所有字符串也必须用双引号)，如果解析失败将抛出一个错误。从jQuery 1.9开始，空内容的响应将返回null或{}。
  • 'jsonp': JSONP格式。使用JSONP形式调用函数时，如"url?callback=?"，jQuery将自动替换第二个?为正确的函数名，以执行回调函数。
  • 'text': 返回纯文本字符串。

• error:Function/Array类型 指定请求失败时执行的回调函数。该函数有3个参数：jqXHR对象、 请求状态字符串(null、 'timeout'、 'error'、 'abort'和'parsererror')、 错误信息字符串(响应状态的文本描述部分，例如'Not Found'或'Internal Server Error')。这是一个Ajax事件。跨域脚本和跨域JSONP请求不会调用该函数。

  从jQuery 1.5开始，该属性值可以是数组形式的多个函数，每个函数都将被回调执行。

• global:Boolean类型 默认值：true。

  指示是否触发全局Ajax事件。将该值设为false将阻止全局事件处理函数被触发，例如ajaxStart()和ajaxStop()。它可以用来控制各种Ajax事件。

• headers:Object类型 默认值：{}。

  以对象形式指定附加的请求头信息。请求头X-Requested-With: XMLHttpRequest将始终被添加，当然你也可以在此处修改默认的 XMLHttpRequest值。headers中的值可以覆盖beforeSend回调函数中设置的> 请求头(意即beforeSend先被调用)。

$.ajax({
    url: "my.php" ,
    headers: {
        "Referer": "https://codeplayer.vip" // 有些浏览器不允许修改该请求头
        ,"User-Agent": "newLine" // 有些浏览器不允许修改该请求头
        ,"X-Power": "newLine"
        ,"Accept-Language": "en-US"
    }
});

• ifModified:Boolean类型 默认值：false。

  允许当前请求仅在服务器数据改变时获取新数据(如未更改，浏览器从缓存中获取数据)。它使用HTTP头信息Last-Modified来判断。从jQuery 1.4开始，他也会检查服务器指定的'etag'来确定数据是否已被修改。

• isLocal:Boolean类型 1.5.1 新增; 默认值：取决于当前的位置协议。

  允许将当前环境视作"本地"，(例如文件系统)，即使默认情况下jQuery不会如此识别它。目前，以下协议将被视作本地：file、*-extension和widget。

• jsonp:String类型 重写JSONP请求的回调函数名称 。该值用于替代"url?callback=?"中的"callback"部分。

• jsonpCallback: String/Function类型 为JSONP请求指定一个回调函数名。这个值将用来取代jQuery自动生成的随机函数名。

  从jQuery 1.5开始，你也可以指定一个函数来返回所需的函数名称。

• mimeType:String类型 1.5.1 新增; 一个mime类型用来覆盖XHR的mime类型。

• password:String类型 用于响应HTTP访问认证请求的密码。

• processData:Boolean类型 默认值：true。

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

• scriptCharset:String类型 设置该请求加载的脚本文件的字符集。只有当请求时dataType为"jsonp"或"script"，并且type是"GET"才会用于强制修改charset。这相当于设置<script>标签的charset属性。通常只在当前页面和远程数据的内容编码不同时使用。

• statusCode:Object类型 1.5 新增; 默认值: {}。

  一组数值的HTTP代码和函数构成的对象，当响应时调用了相应的代码。例如：

$.ajax({
    url: a_not_found_url ,
    // 当响应对应的状态码时，执行对应的回调函数
    statusCode: {
        404: function() {
            alert( "找不到页面" );
        },
        200: function(){
            alert("请求成功");
        }
    }
});

• success: Function/Array类型 指定请求成功后执行的回调函数。该函数有3个参数：请求返回的数据、响应状态字符串、jqXHR对象。

  从jQuery 1.5开始，该属性值可以是数组形式的多个函数，每个函数都将被回调执行。

• timeout: Number类型 设置请求超时的毫秒值。

• traditional:Boolean类型 如果你希望使用传统方式来序列化参数，将该属性设为true。

• type:String类型 默认值："GET"。

  请求类型，可以为'POST'或'GET'。注意：你也可以在此处使用诸如'PUT'、'DELETE'等其他请求类型，但它们不被所有浏览器支持。

• url:String类型 默认值：当前页面URL。

  请求的目标URL。

• username:String类型 用于响应HTTP访问认证请求的用户名。

• xhr:Function类型 默认值：在IE下是ActiveXObject(如果可用)，在其他浏览器中是XMLHttpRequest。

  一个用于创建并返回XMLHttpRequest对象的回调函数。你可以重写该属性以提供自己的XHR实现，或增强其功能。

• xhrFields:Object类型1.5.1 新增; 一个具有多个"字段名称-字段值"对的对象，用于对本地XHR对象进行设置。一对“文件名-文件值”在本机设置XHR对象。例如，如果需要，你可以用它来为跨域请求设置XHR对象的withCredentials属性为true。

$.ajax({
   url: a_cross_domain_url,
   // 将XHR对象的withCredentials设为true
   xhrFields: {
      withCredentials: true
   }
});

注意： 1、如果你的所有AJAX请求都需要设置settings中某些参数，你可以使用jQuery.ajaxSetup()函数进行全局设置，而无需在每次执行jQuery.ajax()时分别设置。 2、在jQuery 1.4(含)之前，选项参数complete、succes、error等Ajax事件的回调函数的第3个参数不是经过jQuery封装的jqXHR对象，而是原生的XMLHttpRequest对象。

• 返回值

  • jQuery.ajax()函数的返回值为jqXHR类型，返回当前该请求的jqXHR对象(jQuery 1.4及以前版本返回的是原生的XMLHttpRequest对象)。

  示例&说明

  如果没有给jQuery.ajax()指定任何参数，则默认请求当前页面，并且不对返回数据进行处理。

  jQuery.ajax()函数的settings对象中，常用的属性有：url、type、async、data、dataType、success、error、complete、beforeSend、timeout等。

$.ajax({
     url: "jquery_ajax.php"
    , type: "POST"
    , data: "name=codeplayer&age=18"
    , success: function( data, textStatus, jqXHR ){
        // data 是返回的数据
        // textStatus 可能为"success"、"notmodified"等
        // jqXHR 是经过jQuery封装的XMLHttpRequest对象
        alert("返回的数据" + data);
    }
});

$.ajax({
     url: "jquery_ajax.php?page=1&id=3"
    , type: "POST"
    // jQuery会自动将对象数据转换为 "name=codeplayer&age=18&uid=1&uid=2&uid=3"
    , data: { name:"codeplayer", age:18, uid: [1, 2, 3] }
    // 请求成功时执行
    , success: function( data, textStatus, jqXHR ){
        alert("返回的数据" + data);
    }
    // 请求失败时执行
    , error: function(jqXHR, textStatus, errorMsg){
        // jqXHR 是经过jQuery封装的XMLHttpRequest对象
        // textStatus 可能为： null、"timeout"、"error"、"abort"或"parsererror"
        // errorMsg 可能为： "Not Found"、"Internal Server Error"等
        alert("请求失败：" + errorMsg);
    }
});

// 将url单独提取出来作为第一个参数(jQuery 1.5+才支持)
$.ajax("jquery_ajax.php?action=type&id=3", {
     dataType: "json" // 返回JSON格式的数据
    , success: function( data, textStatus, jqXHR ){
        // 假设返回的字符串数据为{ "name": "CodePlayer", age: 20 }
        // jQuery已帮我们将该JSON字符串转换为对应的JS对象，可以直接使用
        alert( data.name ); // CodePlayer
    }   
});

$.ajax( {
    // 注意这里有个参数callback=?
     url: "http://cross-domain/jquery_ajax.php?name=Jim&callback=?&age=21"
    , async: false // 同步请求，发送请求后浏览器将被锁定，只有等到该请求完成(无论成功或失败)后，用户才能操作，js代码才会继续执行
    , dataType: "jsonp" // 返回JSON格式的数据
    , success: function( data, textStatus, jqXHR ){
        // 假设返回的字符串数据为{ "site_name": "CodePlayer", "site_desc": "专注于编程开发技术分享" }
        // jQuery已帮我们将该JSON字符串转换为对应的JS对象，可以直接使用
        alert( data.site_desc ); // 专注于编程开发技术分享
    }   
});

$.ajax( {
    // 加载指定的js文件到当前文档中
     url: "http://code.jquery.com/jquery-1.8.3.min.js"
    , dataType: "script"
});