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:'flash' }   ). The transaction will use the specified transport instead of the default transport, when specified in the transaction's configuration object. 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();
}); 

安全公告
已知的问题