Socket.io客户端API

官方文档直译

---

原文地址:http://socket.io/docs/client-api/#

---

IO(url:String, opts:Object):Socket

暴露在window中作为全局的接口如果被单独创建（例如：/socket.io/socket.io.js或者使用CDN），则结果应该使用require('socket.io-client')。

Exposed as the io global in window if using the standalone build (eg: /socket.io/socket.io.js or the CDN), or the result of calling require('socket.io-client').

当被调用，它会根据提供的URL创建一个新的Manager，并且将这个已经存在的Manager返回给之后调用这个方法的对象， 除非multiplex选项被设置为false。设置这个选项等价于设置'force new connection': true。

When called, it creates a new Manager for the given URL, and attempts to reuse an existing Manager for subsequent calls, unless the multiplex option is passed with false. Passing this option is the equivalent of passing 'force new connection': true.

其余的选项被传递给Manager的构造函数（详细说明见下面）。

The rest of the options are passed to the Manager constructor (see below for details).

一个Socket实例是在URL中通过路径名返回指定的命名空间，默认为/。例如，如果一个url是http://localhost/users，一个传输连接将被与http://localhost建立，并且 一个 Socket.IO 连接将会被与/users建立

A Socket instance is returned for the namespace specified by the pathname in the URL, defaulting to /. For example, if the url is http://localhost/users, a transport connection will be established to http://localhost and a Socket.IO connection will be established to
/users.

IO#协议

客户端工作的Socket.io协议版本号。

IO#Socket

参考Socket构造函数。

IO#Manager

参考Manager构造函数。

IO#Emitter

参考Emitter构造函数。

Manager(url:String, opts:Object)

一个Manager代表着一个和Socket.IO服务建立的链接。一个或更多Socket实例都是和这个manager又联系的。对于 每个Socket实例都可以通过io来被这个manager联系。

A Manager represents a connection to a given Socket.IO server. One or more Socket instances are associated with the manager. The manager can be accessed through the io property of each Socket instance.

opts通常在Socket初始化时传递给底层的engine.io。

The opts are also passed to engine.io upon initialization of the underlying Socket.

选项:

• reconnection是否自动重新连接（true）。
• reconnectionDelay多长时间后建立一个新的连接（1000）。
• reconnectionDelayMax重新连接的最大等待时间（5000）。每一个尝试重新连接都由reconnectionDelay在指定的数量上增加。
• timeout当一个connect_error和connect_timeout事件被发送之前的连接超时。

• reconnection whether to reconnect automatically (true)

• reconnectionDelay how long to wait before attempting a new reconnection (1000)
• reconnectionDelayMax maximum amount of time to wait between reconnections (5000). Each attempt increases the reconnection by the amount specified by reconnectionDelay.
• timeout connection timeout before a connect_error and connect_timeout events are emitted (20000)

事件

• connect。有一个成功的连接则发送该事件。
• connect_error。有一个链接错误则发送该事件。
  参数：
  • Object 错误对象
• connect_timeout。有一个链接超时则发送该事件。
• reconnect。有一个成功的重新连接则发送该事件。
  参数：
  • Number重新连接的次数
• reconnect_attempt。开始一个重新连接则发送该事件。
• reconnecting。正在重新连接则发送该事件。
  参数：
  • Number重新连接的次数
• reconnect_error。有一个重新连接的错误则发送该事件。
  参数：
  • Object 错误对象
• reconnect_failed。在reconnectionAttempts内无法重新连接则发送该事件。

• connect. Fired upon a successful connection.

• connect_error. Fired upon a connection error.
  Parameters:
  • Object error object
• connect_timeout. Fired upon a connection timeout.
• reconnect. Fired upon a successful reconnection.
  Parameters:
  • Number reconnection attempt number
• reconnect_attempt. Fired upon an attempt to reconnect.
• reconnecting. Fired upon an attempt to reconnect.
  Parameters:
  • Number reconnection attempt number
• reconnect_error. Fired upon a reconnection attempt error.
  Parameters:
  • Object error object
• reconnect_failed. Fired when couldn’t reconnect within reconnectionAttempts

取决于Manager，上面的事件也在独立的sockets重新连接的时候被发送。

The events above are also emitted on the individual sockets that reconnect that depend on this Manager.

Manager#reconnection(v:Boolean):Manager

设置reconnection的选项，如果没有传参那么就返回它自己。

Manager#reconnectionAttempts(v:Boolean):Manager

设置reconnectionAttempts选项，如果没有传参那么就返回它自己。

Manager#reconnectionDelay(v:Boolean):Manager

设置reconectionDelay选项，如果没有传参那么就返回它自己。

Manager#reconnectionDelayMax(v:Boolean):Manager

设置reconectionDelayMax选项，如果没有传参那么就返回它自己。

Manager#timeout(v:Boolean):Manager

设置timeout选项，如果没有传参那么就返回它自己。

Socket

事件

• connect。链接中则发送该事件。
• error。有一个链接错误则发送该事件
  参数：
  • Object 错误对象
• disconnect。断开连接则发送该事件。
• reconnect。有一个成功的重新连接则发送该事件
  参数：
  • Number重新连接的次数
• reconnect_attempt。开始一个重新连接则发送该事件。
• reconnecting。正在重新连接则发送该事件。
  参数：
  • Number重新连接的次数
• reconnect_error。有一个重新连接的错误则发送该事件。
  参数：
  • Object 错误对象
• reconnect_failed。在reconnectionAttempts内无法重新连接则发送该事件。

• connect. Fired upon connecting.

• error. Fired upon a connection error
  Parameters:
  • Object error data
• disconnect. Fired upon a disconnection.
• reconnect. Fired upon a successful reconnection.
  Parameters:
  • Number reconnection attempt number
• reconnect_attempt. Fired upon an attempt to reconnect.
• reconnecting. Fired upon an attempt to reconnect.
  Parameters:
  • Number reconnection attempt number
• reconnect_error. Fired upon a reconnection attempt error.
  Parameters:
  • Objecterror object
• reconnect_failed. Fired when couldn’t reconnect within reconnectionAttempts