EventSource
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Примечание: Эта возможность доступна в Web Workers.
EventSource
— это интерфейс веб-контента для отправляемых сервером событиям.
Экземпляр EventSource
открывает постоянное соединение с HTTP-сервером, который отправляет события в формате text/event-stream
.
Соединение остаётся открытым до тех пор, пока не будет закрыто вызовом EventSource.close()
.
После открытия соединения входящие сообщения с сервера доставляются в клиентский код в виде событий.
Если во входящем сообщении есть поле события, то вызывается событие, совпадающее со значением этого поля.
Если поле события отсутствует, то запускается общее событие message
.
В отличие от WebSockets, отправляемые сервером события являются однонаправленными, то есть сообщения с данными доставляются в одном направлении, от сервера к клиенту (например, веб-браузеру пользователя).
Это делает их отличным выбором, когда нет необходимости отправлять данные в форме сообщений от клиента к серверу. Например, EventSource
будет полезным для реализации таких функций, как обновление новостной ленты и статуса в социальных сетях, доставки данных в механизм хранилища на стороне клиента, такой как IndexedDB или веб-хранилища.
Предупреждение:Без использования HTTP/2, максимальное количество открытых SSE-соединений может быть ограничено, что может быть особенно заметным при открытии нескольких вкладок, поскольку ограничение действует на браузер и установлено в очень низкое значение (6). Эта проблема отмечена как «Не будет исправлена» в Chrome и Firefox. Ограничение действует на связку «браузер + домен», то есть можно открыть только 6 SSE-соединений к www.example1.com
для всех вкладок и ещё 6 SSE-соединений к www.example2.com
(согласно StackOverflow). При использовании HTTP/2, максимальное количество одновременных HTTP-потоков согласовывается между сервером и клиентом (по умолчанию оно равно 100).
Конструктор
EventSource()
-
Создаёт новый
EventSource
для обработки отправленных сервером событий с указанного URL-адреса, при необходимости с учётными данными.
Свойства экземпляра
Этот интерфейс наследует свойства своего родителя, EventTarget
.
EventSource.readyState
Только для чтения-
Число, представляющее состояние соединения. Допустимые значения:
CONNECTING
(0
),OPEN
(1
) илиCLOSED
(2
). EventSource.url
Только для чтения-
Строка, представляющая URL-адрес источника.
EventSource.withCredentials
Только для чтения-
Логическое значение, указывающее, был ли объект
EventSource
создан с кросс-доменными (CORS) учётными данными (true
) или нет (false
, по умолчанию).
Методы экземпляра
Этот интерфейс наследует методы своего родителя, EventTarget
.
EventSource.close()
-
Закрывает соединение и устанавливает атрибут
readyState
в значениеCLOSED
. Если соединение было уже закрыто, то этот метод ничего не делает.
События
error
-
Возникает, когда не удаётся установить соединение с источником событий.
message
-
Возникает при получении данных от источника событий.
open
-
Возникает при открытии соединения с источником событий.
Кроме того, источник событий может отправлять сообщения с полем события, что будет вызывать именованные события, использовать которые можно по значению этого поля.
Примеры
В этом общем примере объект EventSource
создаётся для получения неименованных событий, получаемых от сервера.
Страница с именем sse.php
отвечает за генерацию событий.
const evtSource = new EventSource("sse.php");
const eventList = document.querySelector("ul");
evtSource.onmessage = (e) => {
const newElement = document.createElement("li");
newElement.textContent = `Сообщение: ${e.data}`;
eventList.appendChild(newElement);
};
Каждое полученное событие запускает обработчик onmessage
объекта EventSource
, который, создаёт новый элемент <li>
, записывает в него текст сообщения и добавляет его в элемент списка, который был создан заранее.
Примечание: Полный код этого примера можно найти на GitHub, смотрите Simple SSE demo using PHP.
Для обработки именованных событий необходимо установить обработчик для каждого типа события.
const sse = new EventSource("/api/v1/sse");
/*
* Такой обработчик будет вызываться при поступлении событий такого вида:
*
* event: notice
* data: useful data
* id: some-id
*/
sse.addEventListener("notice", (e) => {
console.log(e.data);
});
/*
* Аналогично, такой код будет обрабатывать события с полем `event: update`
*/
sse.addEventListener("update", (e) => {
console.log(e.data);
});
/*
* Событие "message" является особым случаем.
* Этот обработчик будет вызываться для неименованных событий и для событий с типом `event: message`.
* Он не будет обрабатывать события с другим типом.
*/
sse.addEventListener("message", (e) => {
console.log(e.data);
});
Спецификации
Specification |
---|
HTML Standard # the-eventsource-interface |
Совместимость с браузерами
BCD tables only load in the browser