WebSocket

Объект WebSocket предоставляет API для создания и управления веб-сокет-подключения к серверу, а также для отправки и получения данных в этом подключении.

Конструктор WebSocket принимает один обязательный и один опциональный параметр:

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString protocols
);

WebSocket WebSocket(
  in DOMString url,
  in optional DOMString[] protocols
);
url

URL-адрес к которому подключаться; сервер по этому адресу должен ответить на websocket-запрос.

protocols Необязательный

Протокол в виде строки или массив строк протоколов. Эти строки используются для определения подпротоколов клиента, т.к. один сервер может поддерживать несколько WebSocket-подпротоколов (например, вы можете захотеть, чтобы один сервер мог обрабатывать разные типы взаимодействия в зависимости от указанного протокола). Если вы не укажете значение протокола, по умолчанию будет использоваться пустая строка.

Конструктор может выбросить исключение:

SECURITY_ERR

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

Обзор метода

void close(in optional unsigned long code, in optional DOMString reason);
void send(in DOMString data);

Атрибуты

Атрибут Тип Описание
binaryType DOMString Строка, указывающая на тип двоичных данных, которые будут переданы по соединению. Это может быть "blob" если будут использованы Blob объекты или "arraybuffer" если будут использованы объекты ArrayBuffer
bufferedAmount unsigned long Количество байтов данных, которые были поставлены в очередь, используя вызовы send, но ещё не переданные в сеть. Это значение не сбрасывается в ноль, при закрытии соединения; если продолжить вызывать send, значение будет расти. Только чтение.
extensions DOMString Расширения, выбранные сервером. В настоящее время это только пустая строка или список расширений, согласованных соединением.
onclose EventListener Обработчик событий, вызываемый, когда readyState WebSocket соединения изменяется на CLOSED. Наблюдатель получает CloseEvent с именем "close".
onerror EventListener Обработчик событий, вызываемый, когда происходит ошибка. Это простое событие, называемое "error".
onmessage EventListener Обработчик событий , вызываемый, когда получается сообщение с сервера. Наблюдатель получает MessageEvent, называемое "message".
onopen EventListener Наблюдатель событий, вызываемый, когда readyState WebSocket - соединения изменяется на OPEN; это показывает, что соединение готово отсылать и принимать данные. Это простое событие, называемое "open".
protocol DOMString Строка, обозначающая имя подпротокола выбранного сервера; это будет одной из строк, указываемой в параметре protocols при создании WebSocket - объекта.
readyState unsigned short Текущее состояние подключения; это одно из Ready state constants. Только для чтения.
url DOMString URL, создаваемый конструктором. Это всегда абсолютный URL. Только для чтения.

Константы

Константы состояния готовности

Эти константы используются атрибутом readyState для описания состояния WebSocket - подключения

Константа Значение Описание
CONNECTING 0 Соединение ещё не открыто.
OPEN 1 Соединение открыто и готово к обмену данными.
CLOSING 2 Соединение в процессе закрытия.
CLOSED 3 Соединение закрыто или не может открыться.

Методы

close()

Закрывает WebSocket - подключение или заканчивает попытку подключения. Если подключение уже закрыто, этот метод не делает ничего.

void close(
  in optional unsigned short code,
  in optional DOMString reason
);
Параметры
code Необязательный

Числовое значение, обозначающее статус-код, описывающий почему подключение будет закрыто. Если параметр не указан, значение по умолчанию равно 1000(обозначает "обмен завершён"). Смотрите list of status codes для CloseEvent, чтобы узнать разрешённые значения.

reason Необязательный

Читаемая человеком строка, объясняющая, почему подключение закрывается. Строка должна быть не длиннее, чем 123 байта UTF-8 текста (не символов).

Возможные исключения
INVALID_ACCESS_ERR

Указан неверный code.

SYNTAX_ERR

Строка reason слишком длинные или содержит непарные суррогаты.

Примечания

В Gecko этот метод не поддерживает никакие параметры включительно до Gecko 8.0.

send()

Передаёт данные на сервер через WebSocket - соединение.

void send(
  in DOMString data
);

void send(
  in ArrayBuffer data
);

void send(
  in Blob data
);
Параметры
data

Текстовая строка, которая будет отправлена на сервер.

Возможные исключения
INVALID_STATE_ERR

Соединение ещё не открыто.

SYNTAX_ERR

Строка data содержит непарные суррогаты

Примечание: Gecko - реализация метода send() несколько отличается от специфицированной в Gecko 6.0; Gecko возвращает boolean, обозначающий, открыто ли соединение до сих пор (и, в дополнение, были ли доставлены данные); это было исправлено в Gecko 8.0.

Начиная с Gecko 11.0, поддержка ArrayBuffer была реализована, но не Blob типы данных.

Спецификации

Спецификация Статус
HTML Living Standard
Определение 'WebSocket' в этой спецификации.		 Живой стандарт

Пример

// Создаёт WebSocket - подключение.
const socket = new WebSocket('ws://localhost:8080');

// Соединение открыто
socket.addEventListener('open', function (event) {
    socket.send('Hello Server!');
});

// Наблюдает за сообщениями
socket.addEventListener('message', function (event) {
    console.log('Message from server ', event.data);
});

Совместимость с браузерами

BCD tables only load in the browser

Смотрите также