API клиента

IO

Метод io привязан к глобальной области видимости в автономном билде:

<script src="/socket.io/socket.io.js"></script>
<script>
  const socket = io();
</script>

Также доступен пакет ESM с версии 4.3.0:

<script type="module">
  import { io } from "https://cdn.socket.io/4.4.1/socket.io.esm.min.js";

  const socket = io();
</script>

С помощью карты импорта:

<script type="importmap">
  {
    "imports": {
      "socket.io-client": "https://cdn.socket.io/4.4.1/socket.io.esm.min.js"
    }
  }
</script>

<script type="module">
  import { io } from "socket.io-client";

  const socket = io();
</script>

В противном случае (с некоторыми инструментами сборки, в Node.js или React Native) его можно импортировать из пакета socket.io-client$:

// ES modules
import { io } from "socket.io-client";

// CommonJS
const { io } = require("socket.io-client");

io.protocol

• <number>

Номер ревизии протокола (в настоящее время: 5).

Протокол определяет формат пакетов, обмениваемых между клиентом и сервером. Клиент и сервер должны использовать одну и ту же ревизию для понимания друг друга.

Дополнительную информацию можно найти здесь.

io([url][, options])

• url <string> (по умолчанию window.location)
• options <Object>
  • forceNew <boolean> создать новое подключение
• Возвращает <Socket>

Создает новый Manager для заданного URL и пытается повторно использовать существующее Manager для последующих вызовов, если не передан опция multiplex со значением false. Передача этой опции эквивалентна передаче "force new connection": true или forceNew: true.

Возвращается новый экземпляр Socket для пространства имен, указанного в пути URL, по умолчанию /. Например, если url равно http://localhost/users, будет установлено транспортное соединение с http://localhost и соединение Socket.IO с /users.

Параметры запроса также можно указать с помощью опции query или непосредственно в URL (пример: http://localhost/users?token=abc).

Для понимания внутренних процессов, рассмотрим пример:

import { io } from "socket.io-client";

const socket = io("ws://example.com/my-namespace", {
  reconnectionDelayMax: 10000,
  auth: {
    token: "123"
  },
  query: {
    "my-key": "my-value"
  }
});

который является сокращенной версией:

import { Manager } from "socket.io-client";

const manager = new Manager("ws://example.com", {
  reconnectionDelayMax: 10000,
  query: {
    "my-key": "my-value"
  }
});

const socket = manager.socket("/my-namespace", {
  auth: {
    token: "123"
  }
});

Полный список доступных опций можно найти здесь.

Менеджер

Manager управляет экземпляром клиента Engine.IO клиент, который является низкоуровневым движком, устанавливающим соединение с сервером (используя транспортные средства, такие как WebSocket или HTTP long-polling).

Manager обрабатывает логику повторного подключения.

Один Manager может быть использован несколькими сокетами. Подробнее о многопоточности можно узнать здесь.

Обратите внимание, что в большинстве случаев вы не будете использовать менеджер напрямую, а вместо этого будете использовать экземпляр сокет.

new Manager(url[, options])

• url <string>
• options <Object>
• Возвращает <Manager>

Полный список доступных опций можно найти здесь.

import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com");

const socket = manager.socket("/"); // main namespace
const adminSocket = manager.socket("/admin"); // admin namespace

manager.reconnection([value])

• value <boolean>
• Возвращает <Manager> | <boolean>

Устанавливает опцию reconnection, или возвращает её, если параметры не переданы.

manager.reconnectionAttempts([value])

• value <number>
• Возвращает <Manager> | <number>

Устанавливает опцию reconnectionAttempts, или возвращает её, если параметры не переданы.

manager.reconnectionDelay([value])

• value <number>
• Возвращает <Manager> | <number>

Устанавливает опцию reconnectionDelay, или возвращает её, если параметры не переданы.

manager.reconnectionDelayMax([value])

• value <number>
• Возвращает <Manager> | <number>

Устанавливает опцию reconnectionDelayMax, или возвращает её, если параметры не переданы.

manager.timeout([value])

• value <number>
• Возвращает <Manager> | <number>

Устанавливает опцию timeout, или возвращает её, если параметры не переданы.

manager.open([callback])

• callback <Function>
• Возвращает <Manager>

Если менеджер был инициирован с autoConnect до false, запустите новую попытку подключения.

Аргумент callback необязателен и будет вызван после успешной или неудачной попытки.

import { Manager } from "socket.io-client";

const manager = new Manager("https://example.com", {
  autoConnect: false
});

const socket = manager.socket("/");

manager.open((err) => {
  if (err) {
    // an error has occurred
  } else {
    // the connection was successfully established
  }
});

manager.connect([callback])

Синоним manager.open([callback]).

manager.socket(nsp, options)

• nsp <string>
• options <Object>
• Возвращает <Socket>

Создает новый Socket для заданного пространства имен. Только auth ({ auth: {key: "value"} }) считывается из объекта options. Другие ключи будут проигнорированы и должны быть переданы при создании экземпляра new Manager(nsp, options).

Событие: 'error'

• error <Error> объект ошибки

Вызывается при ошибке подключения.

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

Событие: 'reconnect'

• attempt <number> номер попытки повторного подключения

Вызывается при успешном повторном подключении.

socket.io.on("reconnect", (attempt) => {
  // ...
});

Событие: 'reconnect_attempt'

• attempt <number> номер попытки повторного подключения

Вызывается при попытке повторного подключения.

socket.io.on("reconnect_attempt", (attempt) => {
  // ...
});

Событие: 'reconnect_error'

• error <Error> объект ошибки

Вызывается при ошибке попытки повторного подключения.

socket.io.on("reconnect_error", (error) => {
  // ...
});

Событие: 'reconnect_failed'

Вызывается, когда повторное подключение не удалось в течение reconnectionAttempts.

socket.io.on("reconnect_failed", () => {
  // ...
});

Событие: 'ping'

Вызывается при получении пакета ping от сервера.

socket.io.on("ping", () => {
  // ...
});

Сокет

Socket — это базовый класс для взаимодействия с сервером. Socket принадлежит определенному пространству имен (по умолчанию /) и использует подлежащий менеджер для связи.

Socket по сути, является EventEmitter, который отправляет события на сервер и получает события с сервера через сеть.

socket.emit("hello", { a: "b", c: [] });

socket.on("hey", (...args) => {
  // ...
});

Дополнительную информацию можно найти здесь.

socket.id

• <string>

Уникальный идентификатор сеанса сокета. Устанавливается после срабатывания события connect, и обновляется после события reconnect.

const socket = io("http://localhost");

console.log(socket.id); // undefined

socket.on("connect", () => {
  console.log(socket.id); // "G5p5..."
});

socket.connected

• <boolean>

Подключен ли сокет к серверу.

const socket = io("http://localhost");

socket.on("connect", () => {
  console.log(socket.connected); // true
});

socket.disconnected

• <boolean>

Отключен ли сокет от сервера.

const socket = io("http://localhost");

socket.on("connect", () => {
  console.log(socket.disconnected); // false
});

socket.io

• <Manager>

Ссылка на базовый Manager.

socket.on("connect", () => {
  const engine = socket.io.engine;
  console.log(engine.transport.name); // in most cases, prints "polling"

  engine.once("upgrade", () => {
    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
    console.log(engine.transport.name); // in most cases, prints "websocket"
  });

  engine.on("packet", ({ type, data }) => {
    // called for each packet received
  });

  engine.on("packetCreate", ({ type, data }) => {
    // called for each packet sent
  });

  engine.on("drain", () => {
    // called when the write buffer is drained
  });

  engine.on("close", (reason) => {
    // called when the underlying connection is closed
  });
});

socket.connect()

Добавлено в v1.0.0

• Возвращает Socket

Вручную подключает сокет.

const socket = io({
  autoConnect: false
});

// ...
socket.connect();

Также может использоваться для ручного переподключения:

socket.on("disconnect", () => {
  socket.connect();
});

socket.open()

Добавлено в v1.0.0

Синоним socket.connect().

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

• args <any[]>
• ack <Function>
• Возвращает <Socket>

Отправляет событие message. Смотрите socket.emit(eventName[, ...args][, ack]).

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

• eventName <string> | <symbol>
• args <any[]>
• ack <Function>
• Возвращает true

Инициирует событие с указанным строковым именем. Можно передать любые другие параметры. Поддерживаются все сериализуемые структуры данных, включая Buffer.

socket.emit("hello", "world");
socket.emit("with-binary", 1, "2", { 3: "4", 5: Buffer.from([6, 7, 8]) });

Аргумент ack необязателен и будет вызван с ответом сервера.

Клиент

socket.emit("hello", "world", (response) => {
  console.log(response); // "got it"
});

Сервер

io.on("connection", (socket) => {
  socket.on("hello", (arg, callback) => {
    console.log(arg); // "world"
    callback("got it");
  });
});

socket.on(eventName, callback)

Унаследовано от EventEmitter class.

• eventName <string> | <symbol>
• listener <Function>
• Возвращает <Socket>

Регистрирует новый обработчик для данного события.

socket.on("news", (data) => {
  console.log(data);
});

// with multiple arguments
socket.on("news", (arg1, arg2, arg3, arg4) => {
  // ...
});
// with callback
socket.on("news", (cb) => {
  cb(0);
});

socket.once(eventName, callback)

Унаследовано от EventEmitter class.

• eventName <string> | <symbol>
• listener <Function>
• Возвращает <Socket>

Добавляет одноразовую функцию listener для события с именем eventName. В следующий раз, когда будет вызвана eventName, этот обработчик будет удален, а затем вызван.

socket.once("my-event", () => {
  // ...
});

socket.off([eventName][, listener])

Унаследовано от EventEmitter class.

• eventName <string> | <symbol>
• listener <Function>
• Возвращает <Socket>

Удаляет указанный listener из массива обработчиков для события с именем eventName.

const myListener = () => {
  // ...
}

socket.on("my-event", myListener);

// then later
socket.off("my-event", myListener);

Аргумент listener также может быть опущен:

// remove all listeners for that event
socket.off("my-event");

// remove all listeners for all events
socket.off();

socket.listeners(eventName)

Унаследовано от EventEmitter class.

• eventName <string> | <symbol>
• Возвращает <Function[]>

Возвращает массив обработчиков для события с именем eventName.

socket.on("my-event", () => {
  // ...
});

console.log(socket.listeners("my-event")); // prints [ [Function] ]

socket.onAny(callback)

Добавлено в v3.0.0

• callback <Function>

Регистрирует новый обработчик для всех событий.

socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.prependAny(callback)

Добавлено в v3.0.0

• callback <Function>

Регистрирует новый обработчик для всех событий. Обработчик добавляется в начало массива обработчиков.

socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.offAny([listener])

Добавлено в v3.0.0

• listener <Function>

Удаляет ранее зарегистрированный обработчик. Если обработчик не указан, удаляются все обработчики для всех событий.

const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();

socket.listenersAny()

Добавлено в v3.0.0

• Возвращает <Function[]>

Возвращает список зарегистрированных обработчиков для всех событий.

const listeners = socket.listenersAny();

socket.onAnyOutgoing(callback)

Добавлено в v4.5.0

• callback <Function>

Регистрирует новый обработчик для исходящих пакетов.

socket.onAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

socket.prependAnyOutgoing(callback)

Добавлено в v4.5.0

• callback <Function>

Регистрирует новый обработчик для исходящих пакетов. Обработчик добавляется в начало массива обработчиков.

socket.prependAnyOutgoing((event, ...args) => {
  console.log(`got ${event}`);
});

socket.offAnyOutgoing([listener])

Добавлено в v4.5.0

• listener <Function>

Удаляет ранее зарегистрированный обработчик. Если обработчик не указан, удаляются все обработчики для исходящих пакетов.

const myListener = () => { /* ... */ };

socket.onAnyOutgoing(myListener);

// remove a single listener
socket.offAnyOutgoing(myListener);

// remove all listeners
socket.offAnyOutgoing();

socket.listenersAnyOutgoing()

Добавлено в v4.5.0

• Возвращает <Function[]>

Возвращает список зарегистрированных обработчиков для исходящих пакетов.

const listeners = socket.listenersAnyOutgoing();

socket.compress(value)

• value <boolean>
• Возвращает <Socket>

Устанавливает модификатор для последующей отправки события, что данные события будут сжаты только если значение равно true. По умолчанию true если метод не вызывается.

socket.compress(false).emit("an event", { some: "data" });

socket.timeout(value)

Добавлено в v4.4.0

• value <number>
• Возвращает <Socket>

Устанавливает модификатор для последующей эмиссии события, при котором обратный вызов будет вызван с ошибкой, если заданное количество миллисекунд истекло без подтверждения от сервера:

socket.timeout(5000).emit("my-event", (err) => {
  if (err) {
    // the server did not acknowledge the event in the given delay
  }
});

socket.disconnect()

Добавлен в v1.0.0

• Возвращает <Socket>

Вручную отключает сокет. В этом случае сокет не будет пытаться переподключиться.

Связанный код причины отключения:

• сторона клиента: "io client disconnect"
• сторона сервера: "client namespace disconnect"

Если это последний активный экземпляр сокета Manager, то низкоуровневое соединение будет закрыто.

socket.close()

Добавлен в v1.0.0

Синоним socket.disconnect().

Флаг: 'volatile'

Добавлен в v3.0.0

Устанавливает модификатор для последующей эмиссии события, указывающий, что пакет может быть потерян, если:

• сокет не подключен
• низкоуровневый транспорт не готов к записи (например, когда запрос POST уже выполняется в режиме HTTP длительного опроса)

socket.volatile.emit(/* ... */); // the server may or may not receive it

Событие: 'connect'

Срабатывает при подключении к пространству имен (включая успешное переподключение).

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

// BAD
socket.on("connect", () => {
  socket.on("data", () => { /* ... */ });
});

// GOOD
socket.on("connect", () => { /* ... */ });
socket.on("data", () => { /* ... */ });

Событие: 'disconnect'

• reason <string>
• details <DisconnectDetails>

Срабатывает при отключении. Список возможных причин отключения:

В первых двух случаях (явное отключение) клиент не будет пытаться переподключиться, и вам нужно будет вручную вызвать socket.connect().

Во всех остальных случаях клиент будет ожидать небольшую случайную задержку и затем попытается переподключиться:

socket.on("disconnect", (reason) => {
  if (reason === "io server disconnect") {
    // the disconnection was initiated by the server, you need to reconnect manually
    socket.connect();
  }
  // else the socket will automatically try to reconnect
});

Событие: 'connect_error'

• connect_error <Error> объект ошибки

Срабатывает при возникновении ошибки middleware пространства имен.

socket.on("connect_error", (error) => {
  // ...
});