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 (en-US) с именем "close". |
onerror |
EventListener |
Обработчик событий, вызываемый, когда происходит ошибка. Это простое событие, называемое "error". |
onmessage |
EventListener |
Обработчик событий , вызываемый, когда получается сообщение с сервера. Наблюдатель получает MessageEvent (en-US), называемое "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 (en-US) для
CloseEvent
(en-US), чтобы узнать разрешённые значения. 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
типы данных.
Пример
js
// Создаёт 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);
});
Спецификации
Specification |
---|
WebSockets Standard # the-websocket-interface |
Совместимость с браузерами
BCD tables only load in the browser