Sign in Subscribe

Socket.IO Client API

Emi Wang

• 5 min read

原文链接：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(对象)
  • ReturnsSocket

为给予的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 <= 1
  • timeout(数字)在一个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次数内重连失败时触发。

Sign up for more like this.

Enter your email
Subscribe