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 unsupported templ: event.
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
), ouCLOSED
(2
). EventSource.url
Somente leitura-
Uma
DOMString
representando a URL da origem. EventSource.withCredentials
Somente leitura-
Um
Boolean
indicando se aEventSource
foi instanciada com credenciais cross-origin (CORS) definidas (true
) ou não (false
, o padrão).
Eventos
EventSource.onerror
-
É um
unsupported templ: eventchamado quando um erro ocorre e o eventounsupported templ: eventé despachado para o objetoEventSource
. EventSource.onmessage
-
É um
unsupported templ: eventchamado quando um eventounsupported templ: eventé recebido, ou seja, quando uma mensagem está sendo recebida da origem. EventSource.onopen
-
É um
unsupported templ: eventchamado quando um eventounsupported templ: eventé 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
comoCLOSED
. 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.
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