EventSource

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

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

После открытия соединения входящие сообщения с сервера доставляются в клиентский код в виде событий. Если во входящем сообщении есть поле события, то вызывается событие, совпадающее со значением этого поля. Если поле события отсутствует, то запускается общее событие message.

В отличие от WebSockets, отправляемые сервером события являются однонаправленными, то есть сообщения с данными доставляются в одном направлении, от сервера к клиенту (например, веб-браузеру пользователя). Это делает их отличным выбором, когда нет необходимости отправлять данные в форме сообщений от клиента к серверу. Например, EventSource будет полезным для реализации таких функций, как обновление новостной ленты и статуса в социальных сетях, доставки данных в механизм хранилища на стороне клиента, такой как IndexedDB или веб-хранилища.

Конструктор

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

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

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

Спецификации

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

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

• Отправляемые сервером события
• Использование отправляемых сервером событий