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 Соединение закрыто или не может открыться.

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

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

Update compatibility data on GitHub
КомпьютерыМобильные
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome для AndroidFirefox для AndroidOpera для AndroidSafari on iOSSamsung Internet
WebSocketChrome Полная поддержка 4Edge Полная поддержка 12Firefox Полная поддержка 11
Замечания
Полная поддержка 11
Замечания
Замечания See bug 695635.
Нет поддержки 7 — 11
С префиксом Замечания
С префиксом Требует вендорный префикс: Moz
Замечания Message size limited to 16 MB (see bug 711205).
Нет поддержки 4 — 6
Замечания
Замечания Message size limited to 16 MB (see bug 711205).
IE Полная поддержка 10Opera Полная поддержка 12.1Safari Полная поддержка 5WebView Android Полная поддержка ≤37Chrome Android Полная поддержка 18Firefox Android Полная поддержка 14
Замечания
Полная поддержка 14
Замечания
Замечания See bug 695635.
Нет поддержки 7 — 14
С префиксом Замечания
С префиксом Требует вендорный префикс: Moz
Замечания Message size limited to 16 MB (see bug 711205).
Нет поддержки 4 — 6
Замечания
Замечания Message size limited to 16 MB (see bug 711205).
Opera Android Полная поддержка 12.1Safari iOS Полная поддержка 4.2Samsung Internet Android Полная поддержка 1.0
WebSocket() constructorChrome Полная поддержка ДаEdge Полная поддержка ≤79Firefox Полная поддержка 7
Полная поддержка 7
Нет поддержки 4 — 7
Замечания
Замечания Parameter protocols not supported.
IE ? Opera Полная поддержка ДаSafari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка 7Opera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да
binaryTypeChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
bufferedAmountChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
closeChrome Полная поддержка 4Edge Полная поддержка 12Firefox Полная поддержка 8
Полная поддержка 8
Нет поддержки 4 — 8
Замечания
Замечания Parameters not supported, see bug 674716.
IE Полная поддержка 10Opera Полная поддержка 12.1Safari Полная поддержка 5WebView Android Полная поддержка ≤37Chrome Android Полная поддержка 18Firefox Android Полная поддержка 8
Полная поддержка 8
Нет поддержки 4 — 8
Замечания
Замечания Parameters not supported, see bug 674716.
Opera Android Полная поддержка 12.1Safari iOS Полная поддержка 4.2Samsung Internet Android Полная поддержка 1.0
close eventChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да
error eventChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да
extensionsChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка 8IE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка 8Opera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
message eventChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да
oncloseChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
onerrorChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
onmessageChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
onopenChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
open eventChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да
protocolChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
Supports protocol as specified by RFC 6455Chrome Полная поддержка 16Edge Полная поддержка 12Firefox Полная поддержка 11IE Полная поддержка 10Opera Полная поддержка 15Safari Полная поддержка 6WebView Android Полная поддержка ДаChrome Android Полная поддержка 18Firefox Android Полная поддержка 14Opera Android Полная поддержка 14Safari iOS Полная поддержка 6Samsung Internet Android Полная поддержка 1.0
readyStateChrome Полная поддержка 43Edge Полная поддержка 12Firefox Полная поддержка 19IE Полная поддержка 10Opera Полная поддержка 30Safari Полная поддержка 10WebView Android Полная поддержка 43Chrome Android Полная поддержка 43Firefox Android Полная поддержка 19Opera Android Полная поддержка 30Safari iOS Полная поддержка 10Samsung Internet Android Полная поддержка 4.0
sendChrome Полная поддержка 4Edge Полная поддержка 12Firefox Полная поддержка 18
Замечания
Полная поддержка 18
Замечания
Замечания See bug 775368.
Нет поддержки 11 — 18
Замечания
Замечания Only parameter of type ArrayBuffer and String supported.
Нет поддержки 8 — 11
Замечания
Замечания Only parameter of type String supported.
Нет поддержки 4 — 8
Замечания
Замечания Only parameter of type String supported. Returns boolean.
IE Полная поддержка 10Opera Полная поддержка 12.1Safari Полная поддержка 5WebView Android Полная поддержка ≤37Chrome Android Полная поддержка 18Firefox Android Полная поддержка 18
Замечания
Полная поддержка 18
Замечания
Замечания See bug 775368.
Нет поддержки 14 — 18
Замечания
Замечания Only parameter of type ArrayBuffer and String supported.
Нет поддержки 8 — 14
Замечания
Замечания Only parameter of type String supported.
Нет поддержки 4 — 8
Замечания
Замечания Only parameter of type String supported. Returns boolean.
Opera Android Полная поддержка 12.1Safari iOS Полная поддержка 4.2Samsung Internet Android Полная поддержка 1.0
urlChrome Полная поддержка ДаEdge Полная поддержка 12Firefox Полная поддержка ДаIE ? Opera Полная поддержка ДаSafari Полная поддержка ДаWebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка ДаOpera Android Полная поддержка ДаSafari iOS Полная поддержка ДаSamsung Internet Android Полная поддержка Да
Available in workersChrome Полная поддержка ДаEdge Полная поддержка ≤18Firefox Полная поддержка 37IE ? Opera ? Safari ? WebView Android Полная поддержка ДаChrome Android Полная поддержка ДаFirefox Android Полная поддержка 37Opera Android ? Safari iOS ? Samsung Internet Android Полная поддержка Да

Легенда

Полная поддержка  
Полная поддержка
Совместимость неизвестна  
Совместимость неизвестна
Смотрите замечания реализации.
Смотрите замечания реализации.
Требует вендорный префикс или другое имя для использования.
Требует вендорный префикс или другое имя для использования.

См. также