Socket.IO Client API
原文链接:https://github.com/socketio/socket.io-client/blob/master/docs/API.md
仅用于学习参考,欢迎指出翻译错位Q^Q
IO
由io
命名空间暴露在独立架构中,或者说是调用require("socket.io-client")
的结果。
io.protocol
- (数字)
协议版本号
io(url[, options])
url
(字符串)options
(对象)- Returns
Socket
为给予的URL创建一个新的Manager
,并尝试重利用已存在的Manager
管理回调函数,除非multiplex
选项传入的值为false
。该参数选项等同于'force new connection': true
或forceNew: true
。
一个新的Socket
会被返回至命名空间中URL指定的路径名下,默认为/
。例如,如果URL
是http://loccalhost/users
,那么一个传输连接将建立至http://localhost
并且一个Sokcet.IO连接将建立至/users
。
可选参数见new Manager(url[, options])。
Manager
new Manager(url[, options])
url
(字符串)options
(对象)path
(字符串) 路径名,会在服务器端被捕获(/socket.io
)reconnection
(布尔值)是否自动重连(true
)reconnectionAttempts
(数字)放弃之前,试图重连的次数(Infinity
)reconnectionDelay
(数字)在尝试重连开始前需要等待多长时间(1000
)。受+/-randomizationFactor
影响,例如:默认初始延迟在500-1500ms之间。reconnectionDelayMax
(数字)重连间隔等待时间的最大值(5000
)。每次尝试重连延迟时间与上述的随机化一起增加2倍。randomizationFactor
(数字)(0.5
),0 <= randomizationFactor <= 1timeout
(数字)在一个connect_error
和connect_timeout
事件发生前,连接超时前的时间(20000
)autoConnect
(布尔值)该值设为false,在你认为适当的时候不得不调用manager.open
- Returns
Manager
options
也会在初始化底层Socket
时传递给engine.io-client
。了解可选options
见这里。
manager.reconnection([value])
value
(布尔值)- Returns
Manager|Boolean
设置reconnection
选项,或在未传参数时返回其它。
manager.reconnectionAttempts([value])
value
(数字)- Returns
Manager|Number
设置reconnectionAttemps
选项,或在未传参时返回它。
manager.reconnectionDelay([value])
value
(数字)- Returns
Manager|Number
设置reconnectionDelay
选项,或在未传参时返回它。
manager.reconnectionDelayMax([value])
value
(数字)- Returns
Manager|Number
设置reconnectionDelayMax
选项,或在未传参时返回它。
manager.timeout([value])
value
(数字)- Returns
Manager|Number
设置timeout
选项,或在未传参时返回它。
manager.open([callback])
callback
(函数)- Returns
Manager
如果manager在初始化时autoConnect
设置未false
,发出一个新的连接尝试。
callback
参数是可选的,一旦尝试失败/成功它都会被调用。
manager.connect([callback)
和manager.open([callback])
相同。
manager.socket(nsp, options)
nsp
(字符串)options
(对象)- Returns
Socket
在给定的命名空间中创建一个新的Socket
。
Event: 'connect_error'
error
(对象)错误对象
发生连接错误时触发。
Event: 'connect_timeout'
连接超时时触发。
Event: 'reconnect'
attempt
(数字)重连尝试次数
在成功连接之后被触发。
Event: 'reconnect_attempt'
尝试重连时触发。
Event: 'reconnecting'
attempt
(数字)重连尝试的次数
重连成功时触发。
Event: 'reconnect_error'
error
(对象)错误对象
重连尝试发生错误时触发。
Event: 'reconnect_failed'
在reconnectionAttempts
次数内连接失败时触发。
Event: 'ping'
当一个ping包被写出到服务器时被触发。
Event: 'pong'
ms
(数字)ping包发出需要的时间毫秒数(延迟)。
当从服务器收到pong时触发。
Socket
socket.id
- (字符串)
socket独一无二的标识符。在connect
事件触发后设置,在reconnect
事件触发时更新。
var socket = io('http://localhost');
console.log(socket.id); //undefined
socket.on('connect', function () {
console.log(socket.id); //'G5p5...'
});
socket.open()
- Returns
Socket
启动socket。
socket.connect()
和socket.open()
相同。
socket.send([...args][, ack])
args
ack
(函数)- Returns
Socket
发送一个message
事件。见接下来的socket.emit(eventName[, ...args][, ack])
。
socket.emit(eventName[, ...args][, ack])
eventName
(字符串)args
ack
(函数)- Returns
Socket
用字符串名字来区别发送给socket的事件。可以包含其他任何的参数。支持所有系列化的数据结构,包括Buffer
。
socket.emit("hello", "world");
socket.emit("with-binary", 1, "2", {3: "4", 5: new Buffer(6)});
ack
参数是可选的,它会在服务器应答后被调用。
socket.emit("ferret", "tobi", function (data) {
console.log(data); //data will be "woot"
});
//server
//io.on("connection", function (socket) {
//socket.on("ferret", function (name, fn) {
//fn("woot");
//});
//});
socket.on(eventName, callback)
eventName
(字符串)callback
(函数)- Returns
Socket
为给定的事件注册一个新的处理函数。
socket.on("news", function (data) {
console.log(data);
});
socket事实上从Emitter类处继承了所有的方法,once
或off
(移除一个事件监听)。
socket.compress(value)
value
(布尔值)- Returns
Socket
为即将触发的事件添加修饰符,表明事件数据只有当value值为true
时才会被压缩。未调用该方法时默认为true
。
socket.compress(false).emit("an event", {some: "data"});
socket.close()
- Returns
Socket
手动断开socket连接。
socket.disconnect()
和socket.close()
相同。
Event: 'connect'
成功连接包含重连成功时触发。
Event: 'connect_error'
error
(对象)错误对象
连接发生错误时触发。
Event: 'connect_timeout'
连接超时时触发。
Event: 'error'
error
(对象)错误对象
错误发生时触发。
Event: 'disconnect'
断开连接时触发。
Event: 'reconnect'
attempt
(数字)尝试重连次数
重连成功时触发。
Event: 'reconnect_attempt'
attempt
(数字)尝试重连次数
尝试重连时触发。
Event: 'reconnecting'
attempt
(数字)尝试重连次数
尝试重连时触发。
Event: 'reconnect_error'
error
(对象)错误对象
尝试重连发生错误时触发。
Event: 'reconnect_failed'
在reconnectionAttempts
次数内重连失败时触发。