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: Diese Funktion ist in Web Workers verfügbar.

Das EventSource-Interface ist das Interface von Webinhalten für Server-sent Events.

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

EventTarget EventSource

Sobald die Verbindung geöffnet ist, werden eingehende Nachrichten vom Server in Form von Events an Ihren Code übermittelt. Wenn es ein Eventfeld in der eingehenden Nachricht gibt, ist das ausgelöste Event das gleiche wie der Wert des Eventfeldes. Wenn kein Eventfeld vorhanden ist, wird ein generisches message-Event ausgelöst.

Im Gegensatz zu WebSockets sind server-sent Events unidirektional; das bedeutet, dass Datenmeldungen in eine Richtung geliefert werden, vom Server zum Client (wie beispielsweise einem Webbrowser eines Benutzers). Das macht sie zu einer ausgezeichneten Wahl, wenn keine Notwendigkeit besteht, Daten in Nachrichtenform vom Client an den Server zu senden. Zum Beispiel ist EventSource ein nützlicher Ansatz zur Handhabung von Dingen wie Updates in sozialen Medien, News-Feeds oder zur Lieferung von Daten in einen client-seitigen Speicher-Mechanismus wie IndexedDB oder Web Storage.

Warnung: Wenn nicht über HTTP/2 verwendet, leidet SSE unter einer Beschränkung 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, was bedeutet, dass Sie 6 SSE-Verbindungen über alle Tabs zu www.example1.com und weitere 6 SSE-Verbindungen zu www.example2.com öffnen können. (aus Stack Overflow). Bei Verwendung von HTTP/2 wird die maximale Anzahl gleichzeitiger HTTP-Streams zwischen dem Server und dem Client verhandelt (Standardwert ist 100).

Konstruktor

EventSource()

Erstellt ein neues EventSource, um server-sent Events von einer angegebenen URL zu empfangen, optional im Credential-Modus.

Instanzeigenschaften

Dieses Interface erbt auch Eigenschaften von seinem Elternteil, EventTarget.

EventSource.readyState Schreibgeschützt

Eine Zahl, die den Zustand 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 anzeigt, ob das EventSource-Objekt mit Cross-Origin (CORS)-Credentials gesetzt (true) oder nicht (false, der Standardwert) instanziiert wurde.

Instanzmethoden

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, macht die Methode nichts.

Events

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, welches ad-hoc-Ereignisse mit diesem Wert erstellt.

Beispiele

In diesem einfachen Beispiel wird ein EventSource erstellt, um ungeklärte Ereignisse vom Server zu empfangen; eine Seite mit dem Namen sse.php ist verantwortlich für die Erstellung der Events.

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 Event führt dazu, dass der onmessage-Ereignishandler unseres EventSource-Objekts ausgeführt wird. Dieser erstellt seinerseits ein neues <li>-Element und schreibt die Daten der Nachricht hinein, dann hängt er das neue Element an das bereits im Dokument vorhandene Listenelement an.

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

Um benannte Ereignisse zu hören, benötigen Sie einen Listener für jeden Ereignistyp, der gesendet wird.

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