io

Ajax 别名 io，注意，KISSY中不存在名为"ajax"的模块，必须使用名字‘io’。

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

方便起见，你仍可以用S.Ajax，S.Ajax === S.IO。下面介绍个如何通过 io 模块去请求 flickr 上提供的图片数据。看示例：

IO <class>

IO(cfg) => Promise

IO 全局方法，构建 io 请求并发送，传入一个JSON对象，返回一个Promise实例。

parameter

cfg (Object) – 用来配置请求的键值对对象. 所有的配置项都是可选的,可以通过 io.setupConfig() 来设置默认配置.

cfg属性列表包括：

new IO({
    url:'test.html',
    context:document.body,
    complete:function(){
        this.className="complete";
    }
});
{data:[{x:1}]} // 错误
{data:[1]} // 正确
true 时 {x:[1,2]} //=> x[]=1&x[]=2
false 时 {x:[1,2]} //=> x=1&x=2
new IO({
    url:"http://y.com/ping.php",
    xhrFields:{
        withCredentials: true
    }
});
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);
    }
});

IO 实例的属性

IO 实例的方法

IO 全局事件

所有 io 请求都会在 io 模块上触发事件，可通过 IO.on 来捕获所有的 io 请求，例如

var indicator=KISSY.one("#indicator"),
        num;

//发送前显示 loading 状态
IO.on("send",function(){
    num++;
    indicator.show();
});

//发送后隐藏 loading 状态
IO.on("complete",function(){
    num--;
    if(!num)
        indicator.hide();
});

全局事件包括：

example

载入并执行一段脚本

new IO({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });

发送数据给服务器，服务器返回后通知用户

new IO({
   type: "POST",
   url: "some.php",
   data: {
    x:'y'
   },
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });

取得最新的 html 并显示

new IO({
  url: "test.html",
  cache: false,
  success: function(html){
    KISSY.one("#results").html(html);
  }
});

发送 xml 文档给服务器

var xmlDocument=S.parseXML("<a>h</a>");

new IO({
   url: "page.php",
   processData: false,
   contentType:'text/xml',
   data: xmlDocument,
   type:'post'
 });

通过 xhr 发送 form 内容，自动序列化 form 为查询串通过 xhr 发送给服务器端

<form>
    <input name='test' value='v' />
</form>

<script>
    new IO({
        url:'send.php',
        form:'#test',
        type:'post',
        dataType:'json',
        success:function(d,s,xhr){
            alert('success');
        }
    });
</script>

getResponseHeader() <IO 实例方法>

getResponseHeader (key) => String

IO 实例方法，获得对应的响应头值.仅对于 xhr 请求有效.

parameter

key (String) – 响应头名

getNativeXhr() <IO 实例方法>

getNativeXhr () => Xhr

获得内置原生的 io 实例

abort() <IO 实例方法>

abort() => void

如果当前请求还没完成（进行中状态）则中断当前的请求，否则什么也不做.

不仅可以中断 xhr 请求，还可以中断 jsonp 以及 script 请求，如果中断前该请求正在进行中则中断后会触发 error ( textStatus == “abort” ) 以及 complete 回调.

then() <IO 实例方法>

then (success, error) => Promise

监听当前请求的成功和失败，并返回新的 promise 实例

parameter

return

{Promise} - 新的 promise 对象

setupConfig() <static>

setupConfig ( cfg ) => void

为所有的 ajax 请求(包括未来)设定默认配置

parameter

cfg (Object) – 用来配置默认请求配置的键值对对象。其中的每个配置都是可选的.

所有可配置的项参见 IO .通过 setupConfig 设置后，除非单个请求设置了对应的配置值，否则后续所有的 ajax 请求都使用该设置.例如，下面代码在连续访问 ping.php 前，设置了 url 的默认值.

IO.setupConfig({
    url:'ping.php'
});

那么接下来的请求如果没有指定 url 配置，就会使用 ping.php

IO({
    // url 没设置，就为 ping.php
    data : {name:'dan'}
});

example

设置默认的请求地址为 /xmlhttp/ ，并使用 POST 方式。那么接下来的请求都会往/xmlhttp/ 发送请求.

IO.setupConfig({
    url:'/xmlhttp/',
    type:'post'
});

IO({
    data:{x:'mydata'}
});

get() <static>

get ( url , [ data , callback , dataType ] ) => XHR

发送 http get 请求

parameter

return

代表本次请求的 xhrObj

第二种调用方式：

get( url , [ callback , dataType ] ) => XHR

data 可忽略，同上个函数描述.

实际上该函数是 IO 的快捷方式

IO.get = function(url, data, callback, dataType) {
    // data 参数可省略
    if (S.isFunction(data)) {
        dataType = callback;
        callback = data;
        data = undefined;
    }

    return new IO({
        type:"get",
        url: url,
        data: data,
        success: callback,
        dataType: dataType
    });
};

example

请求页面 test.php , 但是忽略返回结果

IO.get("test.php");

请求页面 test.php , 并附带一些参数传递给后端

IO.get("test.php",{
    name:"john".
    time:"2pm"
});

alert 请求成功后返回的结果，数据类型由响应的 content-type 决定

IO.get("test.php",function(d){
    alert(d);
});

alert 请求成功后返回的 json 数据，和响应的 content-type 无关

IO.get("test.php",function(d){
    alert(d);
},"json");

post() <static>

post ( url , [ data , callback , dataType ] ) => XHRObj

发送 http post 请求

parameter

return

代表本次请求的 xhrObj

第二种调用方式：

post( url , [ callback , dataType ] ) => XHR

data 可忽略，同上个函数描述，同样，post也是IO的快捷调用方式

IO.post = function(url, data, callback, dataType) {
    // data 参数可省略
    if (S.isFunction(data)) {
        dataType = callback;
        callback = data;
        data = undefined;
    }

    return new IO({
        type:"post",
        url: url,
        data: data,
        success: callback,
        dataType: dataType
    });
};

post 请求从来不会被缓存，因此 io.cfg.cache 配置可以不用配置.

example

请求页面 test.php , 但是忽略返回结果

IO.post("test.php");

请求页面 test.php , 并附带一些参数传递给后端

IO.post("test.php",{
    name:"john".
    time:"2pm"
});

alert 请求成功后返回的结果，数据类型由响应的 content-type 决定

IO.post("test.php",function(d){
    alert(d);
});

alert 请求成功后返回的 json 数据，和响应的 content-type 无关

IO.post("test.php",function(d){
    alert(d);
},"json");

getJSON <static>

getJSON ( url , [ data , callback ] ) => XHR

发送 http get 请求，无视请求响应的 Content-type，将返回信息解析为 json 作为第一个参数调用 callback 回调.

parameter

return

代表本次请求的 xhrObj

另外一种调用方式

getJSON ( url , [ callback ] ) => XHR

data 可忽略，同上个函数描述。相当于这样调用IO：

IO.getJSON = function(url, data, callback) {
    // data 参数可省略
    if (S.isFunction(data)) {
        dataType = callback;
        callback = data;
        data = undefined;
    }

    return new IO({
        type:"get",
        url: url,
        data: data,
        success: callback,
        dataType: "json"
    });
};

example

查看demo :从 test.js 中加载 json 数据并访问

jsonp() <static>

jsonp ( url , [ data , callback ] ) => void

发送 jsonp 请求，将返回 json 信息作为第一个参数调用 callback 回调.

parameter

另外一种调用方式

jsonp ( url , [ callback ] ) => void

data 可忽略，同上个函数描述，具体实现为：

IO.jsonp = function(url, data, callback) {
    // data 参数可省略
    if (S.isFunction(data)) {
        callback = data;
        data = undefined;
    }

    return new IO({
        type:"get",
        url: url,
        data: data,
        success: callback,
        dataType: "jsonp"
    });
};

example

从 flickr 中动态获取图片信息：demo

upload() <static>

upload ( url , form , [ data , callback , dataType ] ) => XHR

上传文件

parameter

return

代表本次请求的 xhrObj

第二种调用方式：

upload ( url , form,[ callback , dataType ] ) => XHR

对应的IO的实现为：

IO.upload = function(url, form, data, callback, dataType) {
    if (S.isFunction(data)) {
        dataType = callback;
        callback = data;
        data = null;
    }
    return new IO({
        url:url,
        type:'post',
        dataType:dataType,
        form:form,
        data:data,
        success:callback
    });
};

example

向 doUpload.html 上传文件并读取 json 响应：Demo

使用自定义按钮模拟 file input 时，注意请将 file input 设置透明覆盖在自定义按钮上面。

// <button id='myFileUploadButton'>
// <input type='file' id='nativeFile'>
// 不要这样做
KISSY.all('#myFileUploadButton').on('click',function(){
    KISSY.get('#nativeFile').click();
});

serialize() <static>

serialize ( elements ) => String

序列化一系列表单元素为可提交的字符串

parameter

elements (string|Array<HTMLElement>|HTMLElement|KISSY.NodeList) – 代表表单元素（input form select ...）的集合，参数为字符串时，需是选择器格式。

return

序列化后的字符串

是否真的要使用该方法？ ajax 提交的话可以直接设置 form 参数

该方法返回一个将表单元素 url 编码过的字符串，表单元素通常包括 <input> <textarea> <select> ，或者直接对整个 <form>元素的所有表单子孙元素进行序列化

example

下面这段html

<form id='f'>
    <div><input type="text" name="a" value="1" id="a" /></div>
    <div><input type="text" name="b" value="2" id="b" /></div>
    <div><input type="hidden" name="c" value="3" id="c" /></div>
    <div>
        <textarea name="d" rows="8" cols="40">4</textarea>
    </div>
    <div><select name="e">
        <option value="5" selected="selected">5</option>
        <option value="6">6</option>
        <option value="7">7</option>
    </select></div>
    <div>
        <input type="checkbox" name="f" value="8" id="f" />
    </div>
    <div>
        <input type="submit" name="g" value="Submit" id="g" />
    </div>
</form>

运行

S.log(IO.serialize("#f")); //=> a=1&b=2&c=3&d=4&e=5

也可以只序列化一部分

S.log(IO.serialize(S.all("#f").all("input")));
// => a=1&b=2&c=3

该方法不会自动去重，重复的元素会产生具有重复部分的产生串。 只有 successful controls 会被序列化为字符串. 因为表单不是用提交按钮提交的，那么提交按钮不会被序列化。只有具备 name 属性的元素才可能被序列化。文件上传元素不会被序列化

start <event>

当配置初始化后，获取传输对象前触发。事件对象包括一下属性，事件对象包括这些属性

send <event>

请求发送前触发。可用于 loading indicator 显示时机。事件对象同 start 事件.

success <event>

服务器返回成功后触发.事件对象同 start 事件.

error <event>

服务器返回失败后触发.事件对象同 start 事件.

complete <event>

服务器返回（无论成功或失败）后触发.事件对象同 start 事件.

Fork me on GitHub