KISSY基础篇乄KISSY之IO（1）

KISSY之IO（1）

今日任务：了解学习IO模块.

IO，即Ajax，只是KISSY中不存在名称为“ajax”的模块，必须使用名字“io”。

KISSY.use('node,io',function(S,Node,IO){     //use IO });

方便起见，仍可以用S.Ajax，S.Ajax==S.IO。

一、IO

IO ( cfg )：构建 io 请求并发送， 继承自 Promise 。而其中的cfg (Object) – 用来配置请求的键值对对象。所有的配置项都是可选的，可以通过 io.setupConfig()来设置默认配置。

二、Config  Detail

url：{String} - 类型 String。本次请求发送的地址。

accepts：{Object} - 该配置和 dataType 一起确定当前发送给服务器的 Accept头。默认包括：

{     xml: "application/xml, text/xml",     html: "text/html",     text: "text/plain",     json: "application/json, text/javascript" }

dataType：{String}- 期望能够从服务器返回的数据类型。如果没有指定，kissy将尽量从返回的 mimeType | Content-type 相应头中推导出来(‘text/xml’ 将推导出xml， ‘text/json’ 将推导出json)。默认支持的类型（该类型的响应信息会作为第一个参数传到 success complete 回调中）有：

·        “xml” : 返回响应信息代表的 xml 文档。

·        “text” : 返回响应信息串。

·        “html” : 同 “text”。

·        “script” : 将响应信息作为脚本执行。

·        “json” : 返回响应信息代表的 json 对象。

·        “jsonp” : 返回 jsonp 的响应信息代表的 json 对象。

processData：{Boolean}- 默认 true。当 data 为对象时是否用 param() 序列化. 例如当需要传送一个xml或 formdata 到服务器时就不需要paramdata，并且最好同时设置contentType 为合适的值。

async：{Boolean}- 默认true。本次xhr请求是否异步发送，如果你需要同步发送，设置该配置为false,注意同步请求在完成前会锁死浏览器。

cache：{Boolean}- dataType 为 script 或 jsonp 时默认 false，其他默认为 true。false 时则会自动给请求url 加上时间戳。

contentType：{String}- 默认“application/x-www-form-urlencoded”，设置请求头 Content-type，数据总是以 utf-8 的编码传往服务器端。设置false 则不设置Content-type 头 (例如传输 formdata 时需要设置false)。

context：{Object}- 设置回调函数中的 this 值,默认为当前配置项。例如可以把一个 dom 节点作为 complete 回调函数的上下文：

new IO({                url:'test.html',              context:document.body,              complete:function(){         this.className="complete";              } });

crossDomain：{Boolean}- 默认同域请求为false,不同域间为true。设置该值为true，则强制script以及jsonp 请求通过 script 节点发送，用于服务器重定向到其他域脚本的场景。

Data：{String|Object}- 如果为Object 类型则会通过 param() 格式化为字符串。data 不能为嵌套object等复杂类型，例如：不能是{data:[{x:1}]}，可以为{data:[1]}。

serializeArray：{Boolean}- 默认 true。表示序列化 data 时是否给数组值对应的键名加 [] ，例如

·        true 时 {x:[1,2]} //=> x[]=1&x[]=2

·        false 时 {x:[1,2]} //=> x=1&x=2

error：{Function}- error (null, textStatus, io) 请求失败时的回调函数。这个函数接受2个参数：

·        textStatus表示错误信息，包括 “timeout”， “error” ，“abort” 等

·        io 表示这次请求代表的io实例。

success：{Function}- success ( data , textStatus，io) 请求成功时的回调函数。该函数传入三个参数。

·        data : 根据dataType格式化服务器响应信息的响应对象。

·        textStatus : 描述成功的状态，一般是“success”。

·        io : 本次请求的io实例。

complete：{Function}- complete ( data , textStatus , io)请求完成时的回调函数.该函数传入三个参数：

·        data : 根据dataType格式化服务器响应信息的响应对象，失败触发时为null

·        textStatus :描述成功的状态，一般是“success”。

·        io : 本次请求的 io 实例。

无论成功或失败都会触发改回调。

headers：{Object}- 设置这次请求xhr的请求头。

jsonp：{String}- 覆盖这次jsonp请求的callback函数名。这个值可以取代请求url 中 callback=? 的callback。例如 {jsonp:’onJsonLoad’} 会导致 ‘onJsonLoad=?’发送给服务器端。

jsonpCallback：{String|Function}-覆盖这次jsonp请求callback函数对应的值 (callback={jsonpCallback})。这个值将取代 kissy 默认生成的UUID值。当传入函数时，该函数需要返回字符串，每次请求都会调用该函数得到用于替换的字符串。

mimeType：{String}- 跨平台设置xhr的 mimeType。

password：{String}- 对于需要验证的 http 请求设置密码。

username：{String}- 对于需要验证的 http 请求设置用户名。

scriptCharset：{String}- 用于dataType jsonp 和script ，设定传输用的script节点的 charset 属性。只有当返回编码和当前页面编码不一致时使用。

timeout：{Number}- 对这次请求设个超时时间，单位秒。当超时后会触发 error 以及 complete回调，状态字符串为 “timeout”。 

当启用 timeout 时，后端要修改返回格式为:

if(window.$jsonpCallback){

    $jsonpCallback({...});

}

$jsonpCallback为io传递给后端回调函数的名字。

type：{String}- 可取值 “get” 或者“post”.

xhrFields：{Object}- 设置到原生xhr对象的键值对.例如为了在标准浏览器进行跨域请求时携带cookie你可以设置 withCredentials为true。x.com发送请求y.com会携带 y.com的cookie信息。

new IO({     url:"http://y.com/ping.php",     xhrFields:{         withCredentials: true     } });

xdr：{Object}- 设置跨域的具体方式和细节，包括以下配置

src：{String}完全跨域请求的 flash 发送程序地址。当完全跨域时，KISSY io 在ie中将采用 flash发请求，默认采用KISSY自带flash发请求，也可将kissy自带的 flash 部署到其他地方，在src中指定。标准浏览器将采用原生机制。

subDomain：{Object}跨子域时的一些请求配置。

proxy：{String} 指定代理页面的地址。默认“/sub_domain_proxy.html”。例如：x.taobao.com要发送请求给y.taobao.com，就需要设置x.taobao.com的页面document.domain=’taobao.com’，并提供y.taobao.com/sub_domain_proxy.html：<script>document.domain='taobao.com'</script>然后x.taobao.com的页面就可以和y.taobao.com通信了。

form：{String} -如果 form的enctype为 “multipart/form-data`则会采用iframe的方式进行无刷新文件上传，否则将form内的输入域和值序列化后通过 xhr 发送到服务器。

beforeSend：{Function} - 发送请求前的拦截函数，传入参数 （xhrObject,config）

xhrObject为io.XhrObj类型。例如可以通过该函数实现上传进度监控：

var xhr = new IO({     url:'./upload.php',     type:"post",     processData:false,     data:formData,     dataType:'json',     contentType:false,     beforeSend:function (xhr){         // 上传监听 upload         xhr.getNativeXhr().upload.addEventListener('progress', function (ev){             S.log({ 'loaded':ev.loaded, 'total':ev.total});         }); },     success:function (d){         S.log(d);     } });

三、Attributes  Detail

readyState：{Number} - 表示请求完成状态。可用于判断当前请求是否完成。 4 表示完成，否则表示正在进行中.(xhr 会有更多取值，jsonpscript 只有 0(初始化) 1(发送中) 4(完成))。

status：{Number} - 响应状态码. xhr 会有更多取值。jsonp script 只有 200(成功) ，500(出错)。

statusText：{String} - 响应状态字符串. 最终同回调 complete 中的 textStatus 一致。

responseText(responseXML)：{String}- 返回响应对应的text和xml（如果需要）。

四、Methods  Detail

getResponseHeader()：

getResponseHeader (key)

获得对应的响应头值.仅对于xhr请求有效。key (String) – 响应头名。

getNativeXhr()：

getNativeXhr ()

获得内置原生的io实例

abort()：

abort ()

如果当前请求还没完成（进行中状态）则中断当前的请求，否则什么也不做。不仅可以中断xhr请求，还可以中断jsonp以及script请求，如果中断前该请求正在进行中则中断后会触发error(textStatus == “abort” ) 以及complete回调.

then()：

then： (success, error)监听当前请求的成功和失败，并返回新的 promise 实例。

success ：(Function) – 成功回调，参数只有一个，为数组 [data,textStatus,io]。其中 data 为服务器返回数据，textStatus为当前请求状态，io 为当前请求实例。

 Error： (Function) – 失败回调，参数只有一个，为数组 [null,textStatus,io]。

Returns：{Promise} - 新的promise对象。