API клиента

IO

Представлен в виде пространства имён io в автономной сборке или в результате вызова require("socket.io-client").

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

const io = require("socket.io-client");
// or with import syntax
import { io } from "socket.io-client";

io.protocol

• (Число)

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

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

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

io([url][, options])

• url (Строка) (по умолчанию window.location)
• options (Объект)
  • forceNew (Булево), следует ли повторно использовать существующее соединение
• Возвращает 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).

const io = require("socket.io-client");

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

является сокращенной записью:

const { Manager } = require("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"
  }
});

См. new Manager(url[, options]) для списка доступных options.

Обратите внимание: manager.socket("/my-namespace", options ) будет считывать только параметр auth в объекте options. query: {…} и другие необязательные параметры используются только при передаче через экземпляр new Manager(uri, options).

См. Миграция с 2.x на 3.0 для получения дополнительной информации о различиях между параметрами auth и query.

Менеджер

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

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

Один Manager может использоваться несколькими сокет-объектами. Дополнительную информацию об этой функции множественного использования можно найти здесь.

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

new Manager(url[, options])

• url (Строка)
• options (Объект)
• Возвращает Manager

Доступные параметры:

Доступные параметры для подлежащего клиента Engine.IO:

Параметры, доступные только в Node.js для подлежащего клиента Engine.IO:

manager.reconnection([value])

• value (Булево)
• Возвращает Manager|Boolean

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

manager.reconnectionAttempts([value])

• value (Число)
• Возвращает Manager|Number

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

manager.reconnectionDelay([value])

• value (Число)
• Возвращает Manager|Number

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

manager.reconnectionDelayMax([value])

• value (Число)
• Возвращает Manager|Number

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

manager.timeout([value])

• value (Число)
• Возвращает Manager|Number

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

manager.open([callback])

• callback (Функция)
• Возвращает Manager

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

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

manager.connect([callback])

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

manager.socket(nsp, options)

• nsp (Строка)
• options (Объект)
• Возвращает Socket

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

Событие: ‘error’

• error (Объект) объект ошибки

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

Событие: ‘reconnect’

• attempt (Число) номер попытки переподключения

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

Событие: ‘reconnect_attempt’

• attempt (Число) номер попытки переподключения

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

Событие: ‘reconnect_error’

• error (Объект) объект ошибки

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

Событие: ‘reconnect_failed’

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

Событие: ‘ping’

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

Сокет

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

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

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

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

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

socket.id

• (Строка)

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

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

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

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

socket.connected

• (Булево)

Соединение с сервером установлено или нет.

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

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

socket.disconnected

• (Булево)

Соединение с сервером разорвано или нет.

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

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

socket.open()

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

Вручную открывает сокет.

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

// ...
socket.open();

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

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

socket.connect()

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

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

• args
• ack (Функция)
• Возвращает Socket

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

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

• eventName (Строка)
• args
• ack (Функция)
• Возвращает true

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

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

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

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

// server:
//  io.on("connection", (socket) => {
//    socket.on("ferret", (name, fn) => {
//      fn("woot");
//    });
//  });

socket.on(eventName, callback)

• eventName (Строка)
• callback (Функция)
• Возвращает 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);
});

Сокет наследует все методы класса Emitter, такие как hasListeners, once или off (для удаления обработчика события).

socket.onAny(callback)

• callback (Функция)

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

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

socket.prependAny(callback)

• callback (Функция)

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

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

socket.offAny([listener])

• listener (Функция)

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

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

socket.onAny(myListener);

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

socket.offAny();

socket.listenersAny()

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

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

const listeners = socket.listenersAny();

socket.compress(value)

• value (Булево)
• Возвращает Socket

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

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

socket.close()

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

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

socket.disconnect()

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

Событие: ‘connect’

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

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

// note: you should register event handlers outside of connect,
// so they are not registered again on reconnection
socket.on("myevent", () => {
  // ...
});

Событие: ‘disconnect’

• reason (Строка)

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

В первых двух случаях (явное отключение) клиент не будет пытаться переподключиться, и вам необходимо вручную вызвать 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 (Объект) объект ошибки

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

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