EventSource
===========

A interface `EventSource` é usada para receber eventos enviados pelo servidor (server-sent events (en-US)). 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()` (en-US).

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` (en-US) 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` (en-US) Somente leitura 

Uma `DOMString` representando a URL da origem.

`EventSource.withCredentials` (en-US) Somente leitura 

Um `Boolean` (en-US) 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 (en-US)` é despachado para o objeto `EventSource`.

`EventSource.onmessage` (en-US)

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

`EventSource.onopen` (en-US)

É 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()` (en-US)

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 with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* Server-sent events (en-US)
* Usando server-sent events