easy

DocsVersion : 1.0.0

ajax( options )

静态方法Define in : ajax.js

数据交互模块的基础方法,该方法可配置的参数很多,其他的简单易用的方法 getgetJSONpost 都是通过该方法实现的。

参数
  • options
    Object
    必需

    由于可配置的参数较多,具体的参数说明请看下表。

参数 数据类型 说明
async Boolean

是否发起异步请求,为 true 为异步请求,为 false 时,将发起同步请求。同步请求将锁住浏览器,用户其它操作必须等待请求完成才可以执行。默认为 true。

cache Boolean

是否缓存请求,dataType 为 script 和 jsonp 时默认为 false,否则为 true。

contentType String

发送请求到服务端时内容的编码类型。默认值适合大多数情况。默认值为 application/x-www-form-urlencoded; charset=UTF-8。

context Object

回调函数的 this 指针,如果没有设置,默认为 ajax 请求时的 options 参数。

data String | Object

发送到服务端的数据,非 POST 请求,如果是 key/value 形式的数据,将转换成编码过的URI。比如 { foo1 : 'bar1', foo2 : 'bar2' } 将转换成 foo1=bar1&foo2=bar2,如果是字符串形式的参数必须按照这种规则来传参。POST 请求是通过 send 方法来发送数据,无需转换。

dataType String

希望服务端返回的数据类型,该参数必须指定。可用值如下:

xml 返回 XML 文档。

json 返回 JSON 格式的数据。

jsonp 返回 JSONP 格式的数据。

text 返回纯文本字符串。

end Function

请求结束的回调函数,该函数接受两个参数,第一个参数是请求状态文本,第二个参数是模拟的 XMLHttpRequest 对象。

failure Function

请求失败的回调函数,该函数接受两个参数,第一个参数是请求状态文本,第二个参数是模拟的 XMLHttpRequest 对象。

global Boolean

是否触发全局 ajax 回调函数。设置为 false 将不会触发全局 AJAX 事件,默认为 true。

headers Object

添加额外的请求头信息,该设置是在 start 被调用前,如果想对其进行修改可以在 start 回调函数被调用时进行修改。

ifModified Boolean

是否仅在服务器数据改变时才获取新数据,使用 HTTP 请求的 Last-Modified 头信息和检查服务器指定的 etag 来确定数据没有被修改过。默认为 false。

jsonp String

在 jsonp 的请求中设置回调函数的名字,默认的函数名字是 callback。

jsonpCallback String

为 jsonp 的请求设置回调函数名,默认是随机的函数名。指定函数名更方便管理请求,如果要缓存 jsonp 的请求,可以将 cache 参数设置成 true,并指定该参数。

mimeType String

设置覆盖请求的 mime 信息。

password String

用于访问需要身份验证的请求的密码。

parseData Boolean

是否将 key/value 形式的 data 数据转换成 URI 格式的查询字符串。默认为 ture,如果是 false,将不会进行转换。

scriptCharset String

当请求类型为 script 或 jsonp 时,可以指定返回内容的编码,通常只在客户端和服务端编码不一致时才使用。

start Function

请求开始的回调函数,该函数接受一个参数,这个参数是模拟的 XMLHttpRequest 对象。

success Function

请求成功的回调函数,该函数接受三个参数,第一个参数是请求的数据,第二个参数是请求状态文本,第三个参数是模拟的 XMLHttpRequest 对象。

timeout Number

设置请求超时时间,单位为 ms。此设置将覆盖全局设置。

type String

指定请求方式,通常只有 GET 和 POST 请求,默认为 GET 请求。

url String

发送请求的 url 地址。

username String

用于访问需要身份验证的请求的用户名。

xhr Function

需要返回一个 XMLHttpRequest 对象。默认在IE下是 ActiveXObject 而其他情况下是 XMLHttpRequest。可以设置一个 XMLHttpRequest 对象,用于覆盖 easy.js 提供的对象。

xhrFields Object

用于设置一些原生 XMLHttpRequest 的属性和方法,该设置是在 start 函数被调用前。如果想对原生 XMLHttpRequest 的属性和方法进行修改可以在 start 回调函数被调用时进行修改。

返回值
  • promise object

    返回一个 promise 实例,并且集合了模拟的 XMLHttpRequest 对象,具体的有属性和方法的详细说明请看下表。

属性名 数据类型 说明
readyState Number

HTTP 请求状态值。

responseText String

请求响应的文本内容。

responseXML XML

请求响应的 XML文档内容,只有在 dataType 的值是 xml 时才会返回 responseXML。

status Number

服务器返回的 HTTP 状态码。

statusText XML

服务器返回的 HTTP 状态文本。

abort Function

中断请求的方法,该方法接受一个 HTTP 状态文本的参数。

getAllResponseHeaders Function

将响应头信息以字符串格式返回。

getResponseHeader Function

建立响应头的哈希表。

overrideMimeType Function

覆盖响应头的 content-type,可配合 start 回调函数使用,可以在请求发起前修改 content-type。该方法接受一个 mimeType 字符串形式的参数。

setRequestHeader Function

设置请求头。该方法接收两个参数,第一个参数是请求头的属性名,第二个参数是请求头的属性值。

then Function

给该 ajax 请求添加回调,具体使用请参考异步回调的 then 的使用方法。传递给已完成的回调是一个数组,该数组的第一个元素是请求内容,第二个元素是状态文本,第三个元素是模拟的 xhr 对象。传递给已拒绝的回调函数同样是一个数组,该数组的第一个元素是状态文本,第二个参数是模拟的 xhr 对象。

例子1

发起一个 GET 请求,期望服务器返回一组 json 数据。

E.ajax({
    url : 'get1.php',
    type : 'GET',
    dataType : 'json',
    success : function( data ){
        console.log( data );  // 如果请求成功将输出一组 json 数据
    }
});
例子2

发起一个 GET 请求,并向服务器提交数据,期望服务器返回 HTML 字符串。

E.ajax({
    url : 'get2.php',
    type : 'GET',
    data : { foo : 'bar' }
    dataType : 'text',
    success : function( data ){
        console.log( data );  // 如果请求成功将输出 HTML 字符串
    },
    failure : function( statusText ){
        console.log( statusText );  // 如果请求失败将输出失败的 HTTP 状态文本
    },
    end : function( statusText ){
        console.log( statusText );  // 无论请求成功还是失败都将输出失败的 HTTP 状态文本
    }
});
例子3

E.ajax 返回的是一个 promise 对象和 xhr 对象的集合体,所以可以给该方法很方便的绑定回调。

E.ajax({
    url : 'get1.php',
    type : 'GET',
    dataType : 'json'
})
.then(function( arg ){
    // 请求成功的内容
    console.log( arg[0] ); 
    // 请求成功的状态文本
    console.log( arg[1] );
    // 模拟的xhr对象
    console.log( arg[2] );
}, function( arg ){
    // 请求失败的状态文本
    console.log( arg[0] );
    // 模拟的xhr对象
    console.log( arg[1] );
})