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.

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Das EventSource-Interface ist die Schnittstelle von Webinhalten zu servergesendeten Ereignissen.

Eine EventSource-Instanz öffnet eine persistente Verbindung zu einem HTTP-Server, der Ereignisse im text/event-stream-Format sendet. Die Verbindung bleibt offen, bis sie durch Aufruf von EventSource.close() geschlossen wird.

EventTarget EventSource

Sobald die Verbindung geöffnet ist, werden eingehende Nachrichten vom Server als Ereignisse an Ihren Code übermittelt. Wenn im eingehenden Nachrichtentext ein Ereignisfeld vorhanden ist, entspricht das ausgelöste Ereignis dem Wert des Ereignisfelds. Wenn kein Ereignisfeld vorhanden ist, wird ein generisches message-Ereignis ausgelöst.

Im Gegensatz zu WebSockets sind servergesendete Ereignisse unidirektional; das heißt, Datenmeldungen werden in eine Richtung gesendet, nämlich vom Server zum Client (wie etwa einem Webbrowser eines Benutzers). Das macht sie zu einer ausgezeichneten Wahl, wenn es nicht nötig ist, Daten in Form von Nachrichten vom Client an den Server zu senden. Beispielsweise ist EventSource eine nützliche Methode für die Verarbeitung von Dingen wie Statusaktualisierungen in sozialen Medien, Newsfeeds oder das Einpflegen von Daten in einen clientseitigen Speicher Mechanismus wie IndexedDB oder Web Storage.

Warnung: Wenn nicht über HTTP/2 verwendet, leidet SSE unter einer Begrenzung der maximalen Anzahl offener Verbindungen, was besonders schmerzhaft sein kann, wenn mehrere Tabs geöffnet werden. Das Limit ist pro Browser und auf eine sehr niedrige Zahl (6) festgelegt. Das Problem wurde in Chrome und Firefox als „Wird nicht behoben“ markiert. Dieses Limit gilt pro Browser und Domain. Das bedeutet, Sie können 6 SSE-Verbindungen über alle Tabs zu www.example1.com und weitere 6 SSE-Verbindungen zu www.example2.com öffnen. (von Stack Overflow). Bei der Nutzung von HTTP/2 wird die maximale Anzahl gleichzeitiger HTTP-Streams zwischen Server und Client ausgehandelt (standardmäßig 100).

Konstruktor

EventSource()

Erstellt eine neue EventSource, um servergesendete Ereignisse von einer angegebenen URL zu empfangen, optional im Berechtigungsmodus.

Instanz-Eigenschaften

Dieses Interface erbt auch Eigenschaften von seinem Elternteil, EventTarget.

EventSource.readyState Nur lesbar

Eine Zahl, die den Zustand der Verbindung repräsentiert. Mögliche Werte sind CONNECTING (0), OPEN (1) oder CLOSED (2).

EventSource.url Nur lesbar

Eine Zeichenkette, die die URL der Quelle repräsentiert.

EventSource.withCredentials Nur lesbar

Ein boolescher Wert, der angibt, ob das EventSource-Objekt mit Cross-Origin-CORS-Berechtigungen (true) instanziiert wurde oder nicht (false, die Standardeinstellung).

Instanz-Methoden

Dieses Interface erbt auch Methoden von seinem Elternteil, EventTarget.

EventSource.close()

Schließt die Verbindung, falls vorhanden, und setzt das readyState-Attribut auf CLOSED. Wenn die Verbindung bereits geschlossen ist, tut die Methode nichts.

Ereignisse

error

Wird ausgelöst, wenn eine Verbindung zu einer Ereignisquelle nicht geöffnet werden konnte.

message

Wird ausgelöst, wenn Daten von einer Ereignisquelle empfangen werden.

open

Wird ausgelöst, wenn eine Verbindung zu einer Ereignisquelle geöffnet wurde.

Zusätzlich kann die Ereignisquelle selbst Nachrichten mit einem Ereignisfeld senden, wodurch Ad-hoc-Ereignisse mit diesem Wert erstellt werden.

Beispiele

In diesem einfachen Beispiel wird ein EventSource erstellt, um unbenannte Ereignisse vom Server zu empfangen; eine Seite mit dem Namen sse.php ist für die Ereignisgenerierung verantwortlich.

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

evtSource.onmessage = (e) => {
  const newElement = document.createElement("li");

  newElement.textContent = `message: ${e.data}`;
  eventList.appendChild(newElement);
};

Jedes empfangene Ereignis führt dazu, dass der onmessage-Ereignishandler unseres EventSource-Objekts ausgeführt wird. Dieser erstellt wiederum ein neues <li>-Element und schreibt die Daten der Nachricht hinein, um das neue Element dann dem bereits im Dokument vorhandenen Listenelement anzufügen.

Hinweis: Sie finden ein vollständiges Beispiel auf GitHub — siehe Simple SSE demo using PHP.

Um auf benannte Ereignisse zu hören, benötigen Sie einen Listener für jeden gesendeten Ereignistyp.

js
const sse = new EventSource("/api/v1/sse");

/*
 * This will listen only for events
 * similar to the following:
 *
 * event: notice
 * data: useful data
 * id: some-id
 */
sse.addEventListener("notice", (e) => {
  console.log(e.data);
});

/*
 * Similarly, this will listen for events
 * with the field `event: update`
 */
sse.addEventListener("update", (e) => {
  console.log(e.data);
});

/*
 * The event "message" is a special case, as it
 * will capture events without an event field
 * as well as events that have the specific type
 * `event: message` It will not trigger on any
 * other event type.
 */
sse.addEventListener("message", (e) => {
  console.log(e.data);
});

Spezifikationen

Specification
HTML Standard
# the-eventsource-interface

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch