YUI 3 ：IO
YUI IO是一个通讯工具，用于数据获取和内容更新，它使用XMLHttpRequest对象来用于“同区域”请求，当用于“跨区域”请求时，使用相反的传输工具。
开始
<script src="http://yui.yahooapis.com/3.3.0/build/yui/yui-min.js"
charset="utf-8"></script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('io', function (Y) {
// IO is available and ready for use.
});
一个简单的通讯
io()方法是用于HTTP请求的最主要方法，这个方法接受的两个参数：uri和configuration
uri：这个参数指定通讯的的URI
configuration：这个参数是一个名值对（key value）的对象，它指定通讯的配置。更多的配置参数请参见下面的：The Configuration Object
io()方法返回一个带有下列成员的对象。
id:通讯过程中的唯一标识
abort():终止指定的通讯
isInProgress():放回一个布尔值，指出通讯是否已经完成。
下面是一个GET通讯：
使用IO工具
使用io
模块：
配置对象：
事件：
同步请求：
跨域请求：
序列号HTML表单作为数据：
在HTML表单上上传文件：
设置HTTP头部：
队列：
模块：
Io的 核心和补充 功能 分为 基本 模块和 子模块，来使得在选择需要的功能时，加入适合的模块。
| 模块 |
描述 |
| io-base |
基本的io类，包含了使用HTTP请求的基本函数 |
| io-xdr |
这个子模块扩展了io-base，使用交替的HTTP通讯，增加了跨区域请求的能力。 |
| io-form |
这个子模块扩展了io-base，增加了为POST通讯，序列化HTML表单数据的功能。 |
| io-upload-iframe |
这个子模块扩展了io-base，使用一个框架作为交互通讯，允许使用一个HTML表单上传文件。 |
| io-queue |
这个子模块扩展了io-base，为io提供一个基本的队列接口 |
配置对象：
这个对象是io()方法的第二个参数，所有属性是可选的，如下。
| 属性 |
描述 |
| method (string) |
定义通讯的HTTP方法，如果这个属性没有定义或者忽略的，那么默认的值是GET |
| data (string) |
如果交互的数据被定义成名值对（如，"foo=bar&baz=boo"）,也可以被定义为 a single-level object（例如.{'boo':'bar','baz':'boo'}.），然后被序列化为名值对字符串，为了应用这个功能，子模块querystring-stringify-simple（一个io-base的可选依赖）必须在Y.use()中定义。 |
| headers (object) |
指定交互的HTTP头部和值。（例如，{'Content-Type':'application/xml;charset=utf-8'}） |
| on (object) |
io事件。 These events fire in addition to the global io events（这句话是什么意思？除了全局io事件xxxx） start: complete: success: failure: end: 注意：These events are accessible only to the transaction's subscribers, whereas global io events are accessible by all subscribers.？？？？？what意思 |
| context (object) |
定义事件执行内容，如果没有定义，默认的Y（YUI实例）将被使用。 |
| form (object) |
这个对象指明使用指定HTML表单的标签和值作为数据。 id：这个属性可以被定义为一个HTML表单的id（sting）或者是一个HTML表单对象引用。 useDisable:设置为true时，禁用区域的值被包含，作为数据的一部分。默认值为flase。 |
| xdr (object) |
Defines the transport to be used for cross-domain requests (e.g., use：这个属性指定传输的方式；io-xdr模块提供"native"和"flash"方式。 dataType:当被设置为“xml”时，io将返回XML文档。 |
| sync (boolean) |
当被设置为true，交互将被同步执行 |
| arguments (object) |
可以是对象，数组，字符串或者是数字。在"start"和"end"处理器中是第二个参数，在"complete","success"和"failure"事件处理器中是第三个参数。 |
| timeout |
这个值是交互的事件截至值，单位是毫秒。例如（{timeout:2000}）.当这个时间限制到了之后，交互的Complete事件还没有激发时，这次交互将被取消。 |
响应对象
当一个交互，以XHR对象作为传输工具，响应的数据将作为一个事件处理的对象被传递。
| 字段 | 描述 |
| status | HTTP状况码 |
| statusText | HTTP状况信息 |
| getResponseHeader(headername) | 返回指定的头部标号的字符串值 |
| getAllResponseHeaders() | 返回所有的HTTP 头部作为一个字符串。每一个名值对都以"\n“定界。 |
| responseText | 响应数据作为一个解码字符串。 |
| responseXML | 响应数据作为一个XML文件。 |
注意：涉及到文件上传或者是跨域请求的交互，使用alternate transports，将仅仅populate responseText或者responseXML域。HTTP status和响应头部（response headers）要么是不可取的（inaccessible）要么是无效的。
事件：
两种事件区别不清楚。global 和Transaction。global event，全局事件？；Transaction event 事务事件？
YUI io事件提供了在事务处理（翻译成交互准确不？）过程中获取状态和数据的功能。有两个方面的io事件：global 和transaction。对于所有的事务处理，global event总是被io激发，并且这些事件对所有的订阅者（subscribers）都是有效的。如果它们有定义在Configuration 对象的句柄（handlers），则Transaction events 被创建并激发。global event 的定义结构为：io:eventname 。
以下是subscribe Globle event的例子。
| 事件 | 描述 |
| io:start | 当请求一个资源是被激发。事件句柄参数签名是： function onStart(transactionid, arguments) {
// transactionid : The transaction's ID.
// arguments: Array ['foo','bar'].
}
// Subscribe to "io.start".
Y.on('io:start', onStart, Y, { start: ['foo','bar']; ); |
| io:complete | 当交互完成了，响应的数据有效了，在io:start之后被激发。这是获得响应数据的最早时刻，事件句柄参数签名是： function onComplete(transactionid, response, arguments) {
// transactionid : The transaction's ID.
// response: The response object.
// arguments: Object containing an array { complete: ['foo', 'bar'] }.
}
// Subscribe to "io.complete".
Y.on('io:complete', onComplete,
Y, { complete: ['foo', 'bar'] } ); |
| io:success | 在complete之后激发，（when hte response HTTP status resolves to 2xx？？？？），事件句柄参数签名是： function onSuccess(transactionid, response, arguments) {
// transactionid : The transaction's ID.
// response: The response object.
// arguments: Boolean value "true".
}
// Subscribe to "io.success".
Y.on('io:success', onSuccess, Y, true); |
| io:failure | 在complete之后激发，（when the response HTTP status resolves to 4xx. 5xx，未定义，或者是一个非标准的HTTP状态。大概意思是，比如什么404错误值了的 ）。这个事件也包含‘abort’和‘timeout’情况，事件句柄参数签名是： function onFailure(transactionid, response, arguments) {
// transactionid : The transaction's ID.
// response: The response object. Only status and
// statusText are populated when the
// transaction is terminated due to abort
// or timeout. The status will read
// 0, and statusText will return "timeout"
// or "abort" depending on the mode of
// termination.
// arguments: String "Transaction Failed".
}
// Subscribe to "io.failure".
Y.on('io:failure', onFailure, Y, 'Transaction Failed');
|
| io:end | 在交互结束时激发，在”success“或者”failure“被确定之后， function onEnd(transactionid, arguments) {
// transactionid : The transaction's ID.
// arguments: Number 0.
}
// Subscribe to "io.end".
Y.on('io:end', onEnd, Y, 0); |
| io:xdrReady | 在flash XDR 传送准备使用时激发。当transport初始化完成时，这个事件仅仅激发一次 |
下面的例子证实一个io 交互，这个交互带有订阅到（subscribe to）io:complete上的事件句柄。
// Create a YUI instance using io module.
YUI().use("io-base", function(Y) {
/*
* 为事件"io:complete"创建一个函数作为事件句柄。
*
* 这个函数将接受以下参数：
* - ID：The ID of the transaction
* - response data：Object containing the response data.
* - Argument one defined when subscribing to the event(e.g., "foo").
* - Argument two defined when subscribing to the event(e.g., "bar").
*/
function onComplete(transactionId, responseObject, arg1, arg2) {
/*
* 参数responseObject是响应对象，它提供的属性包括：
* - status
* - statusText
* - getResponseHeader(headerName)
* - getAllResponseHeaders
* - responseText
* - responseXML
*
* 注意：一个XDR交互中，只有responseText或者responseXML是被定义的属性。
*/
};
/*
* 使用Y.on订阅到事件io:complete
*
* - 'io:complete' : 订阅到这个io事件
* - onComplete : 将被定义到io:complete上的事件句柄。
* - Y : 事件句柄执行的内容，在这个例子中，theYUI sandbox？？？（什么意思？）。因为onComplete被定义为一个全局函数。
*
* - 'foo' : The first argument received by the event handler.
* - 'bar' : The second argument received by the event handler.
* Additional arguments can be defined, as desired.
*/
Y.on('io:complete', onComplete, Y, "foo", "bar");
// Starts the transaction.
var request = Y.io(uri);
});
同步事务：
对于同域请求，YUI io可以被指明来发送一个同步请求，它将停止所有的脚本执行，直到transaction完成。当transaction完成，响应数据are directly accessible through the object returned by Y.io(), and the data are also accessible through all io events。当使用同步请求，abort()和isInProgress()无效。
// Create a YUI instance using the io-base module.
YUI().use("io-base", function(Y) {
var cfg,
request;
// Create a configuration object for the synchronous transaction.
cfg = {
sync: true,
arguments: { 'foo' : 'bar' }
};
/*
* var request will contain the following fields, when the
* transaction is complete:
* - id
* - status
* - statusText
* - getResponseHeader()
* - getAllResponseHeaders()
* - responseText
* - responseXML
* - arguments
*/
request = Y.io(uri, cfg);
});
跨域请求：
alternate transport 是什么？
交互方式
默认：XMLHttpRequest
也可以用：flash
这块不会，请高手指教。
序列号HTML表单作为数据：
YUI io能够序列化HTML表单域到一个UTF-8字符串，名值对。如果transaction是HTTP GET，数据将作为查询字符串加到URI上，如果transaction是HTTP POST ，数据将为POST信息。
// Create a YUI instance using the io-form sub-module.
YUI().use("io-form", function(Y) {
// Create a configuration object for the file upload transaction.
// The form configuration should include two defined properties:
// id: This can be the ID or an object reference to the HTML form.
// useDisabled: Set this property to "true" to include disabled
// HTML form fields, as part of the data. By
// default, disabled fields are excluded from the
// serialization.
// The HTML form data are sent as a UTF-8 encoded key-value string.
var cfg = {
method: 'POST',
form: {
id: formObject,
useDisabled: true
}
};
// Define a function to handle the response data.
function complete(id, o, args) {
var id = id; // Transaction ID.
var data = o.responseText; // Response data.
var args = args[1]; // 'ipsum'.
};
// Subscribe to event "io:complete", and pass an array
// as an argument to the event handler "complete".
Y.on('io:complete', complete, Y, { 'foo':'bar' });
// Start the transaction.
var request = Y.io(uri, cfg);
});
在HTML表单中上传文件：
The default XHR transport, used in io, cannot upload HTML form data that include elements of type="file". In this situation, io will use an alternate transport -- an iframe -- to facilitate the transaction. The response data must be one of the following content types: "text/html", "text/plain", "text/xml". The following example shows how to configure a transaction involving file upload：
设置HTTP头部：
YUI().use("io-base", function(Y) {
// 设置一个新的HTTP头部。Set a new default HTTP header.
Y.io.header('Content-Type', 'application/json');
// 移除一个已经存在的头部，使用相同的方法，但忽略它的值。
Y.io.header('Content-Type');
});
队列：
| FIELD | 描述 |
| queue(uri,configuration) | 同io交互，但返回值为id |
| queue.start() | 启动队列，开始处理交互。 |
| queue.stop() | 停止队列，交互将被停止的，知道队列从新启动re-start |
| queue.promote(id) | 移动队列中存储的指定交互到队首 |
| queue.remove(id) | 删除指定的交互。 |
// Create a YUI instance using the io queue sub-module.
//比较简单，不翻译了。
YUI().use("io-queue", function(Y) {
// Stop the queue so transactions can be stored.
Y.io.queue.stop();
// Send four transactions into the queue for storage.
var task0 = Y.io.queue(uri);
var task1 = Y.io.queue(uri);
var task2 = Y.io.queue(uri);
var task3 = Y.io.queue(uri);
// Promote task2 to the top of the queue.
Y.io.queue.promote(task2);
// Purge task3 from the queue.
Y.io.queue.purge(task3);
// Re-start the queue.
// Transactions are sent in the following order: task2, task0, task 1.
// Transaction callbacks, if provided, will be processed in the same
// sequence: task2, task0, task1, regardless of actual response order.
//
Y.io.queue.start();
});
安全公告
已知的问题