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.

A interface EventSource é usada para receber eventos enviados pelo servidor (server-sent events). Ele se conecta via HTTP em um servidor e recebe eventos com o formato text/event-stream. A conexão permanece aberta até ser fechada chamando EventSource.close().

Assim que a conexão estiver aberta, mensagens recebidas do servidor são entregues para o seu código na forma de eventos message.

Ao contrário dos WebSockets, server-sent events são unidirecionais; ou seja, mensagens são entregues em uma direção, do servidor para o cliente (por exemplo, um navegador web). Isso torna-os uma excelente escolha quando não há necessidade de enviar mensagens do cliente para o servidor. Por exemplo, EventSource é uma abordagem útil para lidar com atualizações de status de mídias sociais, feeds de notícias, or entregar dados para um mecanismo de armazenamento do lado cliente como o IndexedDB ou o web storage.

Construtor

EventSource()

Cria um novo EventSource para receber enventos enviados pelo servidor de uma URL específica, opcionalmente no modo de credenciais.

Propriedades

Essa interface também herda propriedades do seu pai, EventTarget.

EventSource.readyState Somente leitura

Um número representando o estado da conexão. Valores possíveis são CONNECTING (0), OPEN (1), ou CLOSED (2).

EventSource.url Somente leitura

Uma DOMString representando a URL da origem.

EventSource.withCredentials Somente leitura

Um Boolean indicando se a EventSource foi instanciada com credenciais cross-origin (CORS) definidas (true) ou não (false, o padrão).

Eventos

EventSource.onerror

É um event handler chamado quando um erro ocorre e o evento error é despachado para o objeto EventSource.

EventSource.onmessage

É um event handler chamado quando um evento message é recebido, ou seja, quando uma mensagem está sendo recebida da origem.

EventSource.onopen

É um event handler chamado quando um evento open é recebido, ou seja, logo após a abertura da conexão.

Métodos

Essa interface herda métodos de seu pai, EventTarget.

EventSource.close()

Fecha a conexão, se houver, e define o atributo readyState como CLOSED. Se a conexão já estiver fechada, esse método não faz nada.

Exemplos

Nesse exemplo básico, um EventSource é criado para receber eventos do servidor; a página com o nome "sse.php" é responsável por gerar os eventos.

js
var evtSource = new EventSource("sse.php");
var eventList = document.querySelector("ul");

evtSource.onmessage = function (e) {
  var newElement = document.createElement("li");

  newElement.textContent = "message: " + e.data;
  eventList.appendChild(newElement);
};

Cada evento recebido faz com que o handler do evento onmessage no objeto EventSource seja executado. Ele, em contrapartida, cria um novo elemento <li> e escreve os dados da mensagem nele, e em seguida concatena o novo elemento na lista já presente no documento.

Nota: Você pode encontrar um exemplo completo no GitHub — veja Simple SSE demo using PHP.

Especificações

Specification
HTML Standard
# the-eventsource-interface

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também