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.

* Some parts of this feature may have varying levels of support.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die EventSource-Schnittstelle ist die Schnittstelle von Web-Inhalten zu Server-sent Events.

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

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

Im Gegensatz zu WebSockets sind server-sent events unidirektional; das heißt, Datenmeldungen werden in eine Richtung, vom Server zum Client (wie zum Beispiel dem Webbrowser eines Benutzers), geliefert. Das macht sie zu einer hervorragenden Wahl, wenn es nicht notwendig ist, Daten in Form von Nachrichten vom Client zum Server zu senden. Zum Beispiel ist EventSource ein nützlicher Ansatz für die Handhabung von Dingen wie Social-Media-Statusaktualisierungen, Newsfeeds oder zum Liefern von Daten in einen clientseitigen Speicher Mechanismus wie IndexedDB oder Web Storage.

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

Konstruktor

EventSource(): Erstellt eine neue EventSource, um das Empfangen von server-sent events von einer angegebenen URL zu handhaben, optional im Credentials-Modus.

Instanz-Eigenschaften

Diese Schnittstelle erbt auch Eigenschaften von ihrem übergeordneten Element, EventTarget.

EventSource.readyState Schreibgeschützt: Eine Zahl, die den Status der Verbindung darstellt. Mögliche Werte sind CONNECTING (0), OPEN (1) oder CLOSED (2).
EventSource.url Schreibgeschützt: Ein String, der die URL der Quelle darstellt.
EventSource.withCredentials Schreibgeschützt: Ein boolescher Wert, der angibt, ob das EventSource-Objekt mit Cross-Origin (CORS) Credentials gesetzt (true) instanziiert wurde oder nicht (false, der Standardwert).

Instanz-Methoden

Diese Schnittstelle erbt auch Methoden von ihrem übergeordneten Element, EventTarget.

EventSource.close(): Schließt die Verbindung, falls vorhanden, und setzt das readyState-Attribut auf CLOSED. Wenn die Verbindung bereits geschlossen ist, macht 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.

Darüber hinaus kann die Ereignisquelle selbst Nachrichten mit einem Ereignisfeld senden, das führt zu maßgeschneiderten Ereignissen, die auf diesen Wert abgestimmt sind.

Beispiele

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

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 lässt den onmessage-Ereignishandler unseres EventSource-Objekts laufen. Dieser erstellt wiederum ein neues <li>-Element, schreibt die Nachrichtendaten hinein und fügt das neue Element dem bereits im Dokument vorhandenen Listenelement hinzu.

Hinweis: Sie finden ein vollständiges Beispiel auf GitHub — siehe Einfaches SSE-Demo mit PHP.

Um auf benannte Ereignisse zu hören, benötigen Sie einen Listener für jeden Typ von gesendetem Ereignis.

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 # the-eventsource-interface