We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

Перевод не завершен. Пожалуйста, помогите перевести эту статью с английского.

Объект 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 - соединения изменяется на CLOSED; это показывает, что соединение готово отсылать и принимать данные. Это простое событие, называемое "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 Соединение закрыто или не может открыться.

Mетоды

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 (Firefox 8.0 / Thunderbird 8.0 / SeaMonkey 2.5).

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);
});

См. также

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

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Базовая поддержка (Да) 4.0 (2.0) (Да) (Да) ?

Поддержка подпротокола

? 6.0 (6.0) ? ? ?
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Базовая поддержка ? 7.0 (7.0) ? ? ?
Поддержка подпротокола ? 7.0 (7.0) ? ? ?

Заметки по Gecko

Начиная с Gecko 6.0, конструктор обладает приставкой; необходимо использовать MozWebSocket():

var mySocket = new MozWebSocket("http://www.example.com/socketserver");

Аттрибут extensions не поддерживался в Gecko до Gecko 8.0.

Note: До Gecko 11.0 включительно, исходящие сообщения, посланные с помощью метода send() были лимитированы до 16 MB. Сейчас они могут быть до 2 GB.

Метки документа и участники

Внесли вклад в эту страницу: AlexandritT, Neiromaster, zaqqq13, antenko, izdesenko
Обновлялась последний раз: AlexandritT,