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.

* Some parts of this feature may have varying levels of support.

Примечание: Эта возможность доступна в Web Workers.

EventSource — это интерфейс веб-контента для отправляемых сервером событиям.

Экземпляр EventSource открывает постоянное соединение с HTTP-сервером, который отправляет события в формате text/event-stream. Соединение остаётся открытым до тех пор, пока не будет закрыто вызовом EventSource.close().

EventTarget EventSource

После открытия соединения входящие сообщения с сервера доставляются в клиентский код в виде событий. Если во входящем сообщении есть поле события, то вызывается событие, совпадающее со значением этого поля. Если поле события отсутствует, то запускается общее событие 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 отвечает за генерацию событий.

js
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.

Для обработки именованных событий необходимо установить обработчик для каждого типа события.

js
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
# the-eventsource-interface

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

BCD tables only load in the browser

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