socket.io官方文档翻译4（server api）

服务端API

服务端

通过require('socket.io')引入

new Server(httpServer[, options])

httpServer (http.Server) socket.io所绑定的服务器.
options (Object)
path (String): 捕获路径,默认为(/socket.io)
serveClient (Boolean): 是否充当客户端,默认为 (true)
adapter (Adapter):要使用的适配器。默认为基于内存的socket.io附带的Adapter实例。请参阅socket.io-adapte
origins (String): 允许的源（*）
parser (Parser): 所使用解析器。默认为socket.io附带Parser的一个实例。

直接引用，或者通过new创建一个实例：

const io = require('socket.io')();
// or
const Server = require('socket.io');
const io = new Server();

传递给socket.io的选项总是相同地传递给创建的engine.io服务器。你可以参考engin.io的相关设置选项

在这些选项中：
.pingTimeout（Number）：没有pong数据包考虑多少毫秒后关闭连接（60000）
.pingInterval（Number）：在发送新的ping数据包之前多少ms（25000）

在客户端知道服务器不再可用之前，这两个参数将影响延迟。例如，如果由于网络问题导致基础TCP连接未正确关闭，则客户端可能必须在获取断开连接事件之前等待pingTimeout + pingInterval毫秒。

注意：顺序很重要。默认情况下，首先建立一个长轮询连接，如果可能的话，然后升级到WebSocket。使用['websocket']意味着如果无法打开WebSocket连接，则不会有后备。

const server = require('http').createServer();

const io = require('socket.io')(server, {
  path: '/test',
  serveClient: false,
  // below are engine.IO options
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

new Server(port[,options])
port（数字）要监听的端口（将创建一个新的http.Server）
options（对象）

请参阅上文的可用选项

const server = require('http').createServer();

const io = require('socket.io')(3000, {
  path: '/test',
  serveClient: false,
  // below are engine.IO options
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

new Server(options)
*options(对象)

点这里查看更多可用选项

const io = require('socket.io')({
  path: '/test',
  serveClient: false,
});

// either
const server = require('http').createServer();

io.attach(server, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.listen(3000);

// or
io.attach(3000, {
  pingInterval: 10000,
  pingTimeout: 5000,
  cookie: false
});

server.sockets

(命名空间)
默认命名空间为(/)

server.serveClient([value])

value (Boolean)
Returns Server|Boolean

如果value为true，则连接的服务器（请参阅Server#attach）将为客户端文件提供服务。默认为true。调用attach后，此方法无效。如果未提供参数，则此方法返回当前值。

// pass a server and the `serveClient` option
const io = require('socket.io')(http, { serveClient: false });

// or pass no server and then you can call the method
const io = require('socket.io')();
io.serveClient(false);
io.attach(http);

server.path([value])

value (String)
Returns Server|String

设置engine.io和静态文件将被提供的路径值。默认为/socket.io。如果未提供参数，则此方法返回当前值。

const io = require('socket.io')();
io.path('/myownpath');

// client-side
const socket = io({
  path: '/myownpath'
});

server.adapter([value])

value (Adapter)
Returns Server|Adapter

设置适配器值。默认为基于内存的socket.io附带的Adapter实例。请参阅socket.io-adapter。如果未提供参数，则此方法返回当前值。

const io = require('socket.io')(3000);
const redis = require('socket.io-redis');
io.adapter(redis({ host: 'localhost', port: 6379 }));

server.origins([value])

value (String)
Returns Server|String
设置允许的来源值。默认允许任何来源。如果未提供参数，则此方法返回当前值。

io.origins(['foo.example.com:443']);

server.origins(fn)

fn (Function)
Returns Server
提供一个带有两个参数的函数origin：String和callback（error，success），其中success是一个布尔值，指示源是否被允许。

潜在的缺点：

在某些情况下，当无法确定原点时，它可能具有* 的值。
由于该函数将针对每个请求执行，因此建议使该函数的运行速度尽可能快些。
如果将socket.io与Express，CORS头文件只会受到socket.io请求的影响。对于Express可以使用cors。

io.origins((origin, callback) => {
  if (origin !== 'https://foo.example.com') {
    return callback('origin not allowed', false);
  }
  callback(null, true);
});

server.attach(httpServer[, options])

httpServer (http.Server) 要附加到的服务器
options (Object)
使用提供的选项（可选）将服务器连接到httpServer上的engine.io实例（可选）。

server.attach(port[, options])

port (Number) 要监听的端口
options (Object)

使用提供的选项（可选）将服务器连接到新的http.Server上的engine.io实例（可选）。

server.listen(httpServer[, options])
server.attach(httpServer [, options])的同义词。

server.listen(port[, options])
server.attach(port[, options])的同义词。

server.bind(engine)

engine (engine.Server)
Returns Server

仅限高级使用。将服务器绑定到特定的engine.io服务器（或兼容的API）实例。

server.onconnection(socket)

socket (engine.Socket)
Returns Server

仅限高级使用。从传入的engine.io（或兼容的API）套接字创建一个新的socket.io客户端。

server.of(nsp)

(nsp (String)
Returns Namespace
通过路径名标识符nsp初始化并检索给定的命名空间。如果命名空间已经初始化，它会立即返回。

const adminNamespace = io.of('/admin');

server.close([callback])

callback (Function)
关闭socket.io服务器。回调参数是可选的，并且将在所有连接关闭时调用。

const Server = require('socket.io');
const PORT   = 3030;
const server = require('http').Server();

const io = Server(PORT);

io.close(); // Close current server

server.listen(PORT); // PORT is free to use

io = Server(server);

server.engine.generated
覆盖默认方法以生成您的自定义的socket.id。

该函数使用节点请求对象(http.IncomingMessage)作为第一个参数进行调用。

io.engine.generateId = (req) => {
  return "custom:id:" + custom_id++; // custom id must be unique
}

命名空间

表示在由路径名标识的给定范围下连接的socket池（例如：/ chat）。

客户端总是连接到/（主命名空间），然后可能连接到其他命名空间（同时使用相同的底层连接）。

namespace.name

(String)

名称空间标识符属性。

namespace.connected

(Object)

连接到此名称空间的Socket对象的哈希值，由id索引。

namespace.adapter

(Adapter)

用于命名空间的适配器。使用基于Redis的适配器时很有用，因为它提供了管理集群socket和rooms的方法。

注意：主名称空间的适配器可以通过io.of('/').adapter进行访问。

namespace.to(room)

room (String)
Returns Namespace for chaining

为后续事件发送设置一个修饰符，该事件将只广播给已加入给定房间的客户端。

要发送到多个房间，您可以多次调用to。

const io = require('socket.io')();
const adminNamespace = io.of('/admin');

adminNamespace.to('level1').emit('an event', { some: 'data' });

namespace.in(room)
namespace.to(room)的同义词。

namespace.emit(eventName[, ...args])

eventName (String)
args
向所有连接的客户端发出事件。以下两种写法是等效的：

const io = require('socket.io')();
io.emit('an event sent to all connected clients'); // main namespace

const chat = io.of('/chat');
chat.emit('an event sent to all connected clients in chat namespace');

注意：从命名空间发出时不支持确认。

namespace.clients(callback)

callback (Function)
获取连接到此名称空间的客户端ID列表（如果适用，则跨所有节点）。

const io = require('socket.io')();
io.of('/chat').clients((error, clients) => {
  if (error) throw error;
  console.log(clients); // => [PZDoMHjiu8PYfRiKAAAF, Anw2LatarvGVVXEIAAAD]
});

获得命名空间中的所有客户端的一个例子：

io.of('/chat').in('general').clients((error, clients) => {
  if (error) throw error;
  console.log(clients); // => [Anw2LatarvGVVXEIAAAD]
});

namespace.use(fn)

fn (Function)
注册一个中间件，每传入一个Socket时都会执行该函数，并接收作为参数的套接字和一个函数，以便将执行延迟到下一个注册的中间件。

传递给中间件回调的错误将作为特殊错误数据包发送给客户端。

io.use((socket, next) => {
  if (socket.request.headers.cookie) return next();
  next(new Error('Authentication error'));
});

Event: 'connect'

socket (Socket) 与客服端的socket连接

当有来自客户端的连接时触发。

io.on('connect', (socket) => {
  // ...
});

io.of('/admin').on('connect', (socket) => {
  // ...
});

Event: 'connection'
Event: 'connect'的同义词

标志：'volatile'
为后续事件发射设置一个修饰符，如果客户端不准备接收消息，则可能会丢失事件数据（由于网络缓慢或其他问题，或者因为它们通过长轮询连接并且处于请求-响应周期中）。

io.volatile.emit('an event', { some: 'data' }); //客户端可能也可能接收不到信息

标志：'local'
为后续事件发射设置一个修饰符，该事件数据只会广播到当前节点（使用Redis适配器时）。

Socket

Socket是与浏览器客户端交互的基础类。一个Socket属于某个命名空间（默认为/），并使用一个底层客户端进行通信。

应该注意的是，Socket并不直接与实际的底层TCP/IP socket相关，而只是该类的名称。

在每个名字空间内，你还可以定义Socket可以加入和离开的任意通道（称为空间）。这提供了一种方便的方式来广播到一组socket（请参阅下面的Socket）。

Socket类继承自EventEmitter。 Socket类覆盖emit方法，并且不修改任何其他EventEmitter方法。此处记录的所有方法也为由EventEmitter实现的方法（除emit之外），并且适用于EventEmitter的文档。

socket.id

(String)
会话的唯一标识符，来自底层客户端。

socket.rooms

(Object)
标识客户所在房间的字符串散列，按房间名称索引。

io.on('connection', (socket) => {
  socket.join('room 237', () => {
    let rooms = Object.keys(socket.rooms);
    console.log(rooms); // [ , 'room 237' ]
  });
});

socket.client

(Client)
底层Client对象的引用。

socket.conn

(engine.Socket)
对底层客户端传输连接（engine.io Socket对象）的引用。这允许访问IO传输层，大多数情况它仍然是抽象出的TCP/IP socket连接。

socket.request

(Request)
一个getter代理，用于返回发起底层engine.io客户端的请求的引用。用于访问Cookie或User-Agent等请求标头。

socket.handshake
*(Object)

握手细节：

{
  headers: /* 握手部分的头 */,
  time: /* 创建时间 (字符串) */,
  address: /* 客户端ip地址 */,
  xdomain: /* 连接是否跨域 */,
  secure: /* 连接是否安全 */,
  issued: /* 创建数据 (unix 时间戳) */,
  url: /* 请求url地址 */,
  query: /* 询问对象 */
}

用法：

io.use((socket, next) => {
  let handshake = socket.handshake;
  // ...
});

io.on('connection', (socket) => {
  let handshake = socket.handshake;
  // ...
});

socket.use(fn)

fn (Function)
注册一个中间件，这是一个当每传入数据包时执行的函数，其接收数据包的参数和一个函数，选择性地延迟执行到下一个注册的中间件。

传递给中间件回调的错误将作为特殊错误数据包发送给客户端。

io.on('connection', (socket) => {
  socket.use((packet, next) => {
    if (packet.doge === true) return next();
    next(new Error('Not a doge error'));
  });
});

socket.send([...args][, ack])

args
ack (Function)
送消息事件。请参阅socket.emit(eventName [,... args] [,ack])。

socket.emit(eventName[, ...args][, ack])
(overrides EventEmitter.emit)

eventName (String)
args
ack (Function)
Returns Socket
向由字符串名称标识的套接字发出事件。任何其他参数都可以包含在内。所有可序列化的数据结构都受支持，包括Buffer。

socket.emit('hello', 'world');
socket.emit('with-binary', 1, '2', { 3: '4', 5: new Buffer(6) });

ack参数是可选的，并且将与客户的答案一起被调用。

io.on('connection', (socket) => {
  socket.emit('an event', { some: 'data' });

  socket.emit('ferret', 'tobi', (data) => {
    console.log(data); // data will be 'woot'
  });

  // the client code
  // client.on('ferret', (name, fn) => {
  //   fn('woot');
  // });

});

socket.on(eventName, callback)
(inherited from EventEmitter)

eventName (String)
callback (Function)
Returns Socket
为给定事件注册一个新的处理程序。

socket.on('news', (data) => {
  console.log(data);
});
// with several arguments
socket.on('news', (arg1, arg2, arg3) => {
  // ...
});
// or with acknowledgement
socket.on('news', (data, callback) => {
  callback(0);
});

socket.once(eventName, listener)

socket.removeListener(eventName, listener)

socket.removeAllListeners([eventName])

socket.eventNames()
继承自EventEmitter（以及此处未提及的其他方法）。请参阅events模块的Node.js文档。

socket.join(room[, callback])

room (String)
callback (Function)
Returns Socket for chaining

将客户端添加到房间，并可选择触发具有err签名的回调（如果有的话）。

io.on('connection', (socket) => {
  socket.join('room 237', () => {
    let rooms = Objects.keys(socket.rooms);
    console.log(rooms); // [ , 'room 237' ]
    io.to('room 237', 'a new user has joined the room'); // 广播到房间中的每个人
  });
});

连接房间的机制由已配置的适配器处理（请参阅上面的Server#adapter），默认为socket.io-adapter。

io.on('connection', (socket) => {
  socket.on('say to someone', (id, msg) => {
    // send a private message to the socket with the given id
    socket.to(id).emit('my message', msg);
  });
});

socket.join(rooms[, callback])

rooms (Array)
callback (Function)
Returns Socket for chaining

将客户端添加到房间列表中，并可选择触发带有err签名的回调（如果有）。

socket.leave(room[, callback])

room (String)
callback (Function)
Returns Socket for chaining
从房间中删除客户端，并可选择触发err签名（如果有）。

断开后会自动离开房间

socket.to(room)

room (String)
为后续事件发射设置一个修饰符，该事件将仅播放给已加入给定房间的客户端（socket本身被排除）。

要发送到多个房间，您可以多次调用to。

io.on('connection', (socket) => {
  // to one room
  socket.to('others').emit('an event', { some: 'data' });
  // to multiple rooms
  socket.to('room1').to('room2').emit('hello');
  // a private message to another socket
  socket.to(/* another socket id */).emit('hey');
});

注意：广播时不支持确认。

socket.in(room)
Synonym of socket.to(room).

socket.compress(value)

value (Boolean) whether to following packet will be compressed
Returns Socket for chaining
为后续事件发射设置修饰符，该事件数据只有在值为true时才会被压缩。当您不调用该方法时，默认为true。

io.on('connection', (socket) => {
  socket.compress(false).emit('uncompressed', "that's rough");
});

socket.disconnect(close)

close (Boolean) whether to close the underlying connection
Returns Socket

断开这个客户端。如果close值为true，则关闭底层连接。否则，它只是断开命名空间。

io.on('connection', (socket) => {
  setTimeout(() => socket.disconnect(true), 5000);
});

Flag: 'broadcast'
为后续事件发射设置修饰符，以便事件数据会发送给除发送者以外的每个socket。

io.on('connection', (socket) => {
  socket.broadcast.emit('an event', { some: 'data' }); // everyone gets it but the sender
});

Flag: 'volatile'
为后续事件发射设置修饰符，以防事件数据在客户端未准备好接收消息时丢失（由于网络缓慢或其他问题，或者由于它们通过长轮询进行连接并处于请求-响应周期中）。

io.on('connection', (socket) => {
  socket.volatile.emit('an event', { some: 'data' }); // the client may or may not receive it
});

Event: 'disconnect'

reason (String) 断开连接的原因 (客户端或服务器端)

当断开连接时触发

io.on('connection', (socket) => {
  socket.on('disconnect', (reason) => {
    // ...
  });
});

Event: 'error'

error (Object) error object
当错误发生时触发

io.on('connection', (socket) => {
  socket.on('error', (error) => {
    // ...
  });
});

Event: 'disconnecting'

reason（String）断开原因（客户端或服务器端）

当客户端断开连接时（但尚未离开客房）会被触发。

io.on('connection', (socket) => {
  socket.on('disconnecting', (reason) => {
    let rooms = Object.keys(socket.rooms);
    // ...
  });
});

这些是不能用作事件名称的保留事件（例如connect，newListener和removeListener）。

Client

客户端类表示传入的传输（engine.io）连接。客户端可以与许多属于不同命名空间的多路复用socket相关联。

client.conn

(engine.Socket)
引用底层的engine.io Socket连接。

client.request

(Request)
一个getter代理，用于将引用返回给由engine.io连接而发起的请求。用于访问Cookie或User-Agent等请求头。

由于我也是第一次使用socket.io，其中也肯定有许多不准确的地方，如果发现的话，欢迎留言告知

现在基本上只是找个英文文档原模原样的翻译，后面打算自己写一个socket应用，再写一份自己的日志

socket.io官方文档翻译4（server api）

服务端API

服务端

命名空间

Socket

Client

你可能感兴趣的:(socket.io官方文档翻译4（server api）)