NetworkInformation: change — Ereignis · JavaScript-Referenz

Signatur

navigator.connection.addEventListener("change", handler)

Beschreibung

Das change-Ereignis gehört zur Network Information API. Der Browser löst es am Objekt navigator.connection aus, wenn sich eine der gemeldeten Verbindungseigenschaften ändert. Dazu gehören effectiveType (z. B. "4g", "3g"), downlink (geschätzte Bandbreite in Mbit/s), rtt (geschätzte Umlaufzeit in ms), saveData und, wo es unterstützt wird, type.

Du kannst den Handler auf zwei Arten registrieren: mit navigator.connection.addEventListener("change", handler) oder über die Eigenschaft navigator.connection.onchange = handler. Das Ereignisobjekt ist ein einfaches Event ohne eigene Zusatzdaten. Die neuen Werte liest du deshalb direkt aus navigator.connection bzw. event.target.

Typische Einsatzfälle sind adaptive Inhalte: Bei langsamer Verbindung lädst du Bilder oder Videos in geringerer Qualität, schaltest Autoplay und Vorabladen (Prefetching) ab oder berücksichtigst den Datensparmodus (saveData). Bei besserer Verbindung schaltest du diese Funktionen wieder ein.

Das Ereignis sagt nichts darüber aus, ob das Gerät online oder offline ist. Dafür gibt es die Ereignisse online und offline am window-Objekt und die Eigenschaft navigator.onLine.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, hier immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. Sie erhält ein einfaches `Event`-Objekt. `event.target` ist das `NetworkInformation`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive` oder `signal` (für ein Abmelden per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die aktuellen Verbindungswerte liest du im Handler aus navigator.connection.

Beispiele

Verbindungsänderungen protokollieren (addEventListener)

const connection = navigator.connection;

if (connection) {
  const logConnection = () => {
    console.log(
      `Typ: ${connection.effectiveType}, ` +
      `Downlink: ${connection.downlink} Mbit/s, ` +
      `RTT: ${connection.rtt} ms, ` +
      `Datensparmodus: ${connection.saveData}`
    );
  };

  logConnection(); // Ausgangszustand
  connection.addEventListener("change", logConnection);
} else {
  console.log("Network Information API wird nicht unterstützt.");
}

Typ: 4g, Downlink: 10 Mbit/s, RTT: 50 ms, Datensparmodus: false // nach Wechsel ins Mobilfunknetz z. B.: Typ: 3g, Downlink: 1.2 Mbit/s, RTT: 300 ms, Datensparmodus: false

Bildqualität adaptiv anpassen (onchange-Property)

const connection = navigator.connection;

const applyQuality = () => {
  const slow = connection.saveData ||
    ["slow-2g", "2g", "3g"].includes(connection.effectiveType);

  document.documentElement.dataset.quality = slow ? "low" : "high";

  document.querySelectorAll("img[data-src-low][data-src-high]").forEach((img) => {
    img.src = slow ? img.dataset.srcLow : img.dataset.srcHigh;
  });

  console.log(`Qualität: ${slow ? "niedrig" : "hoch"}`);
};

if (connection) {
  applyQuality();
  connection.onchange = applyQuality;
}

Qualität: hoch // nach Verschlechterung der Verbindung: Qualität: niedrig

Listener mit removeEventListener und AbortController wieder entfernen

const connection = navigator.connection;

if (connection) {
  // Variante 1: removeEventListener mit derselben Funktionsreferenz
  const onChange = (event) => {
    console.log("Neuer effectiveType:", event.target.effectiveType);
  };
  connection.addEventListener("change", onChange);
  // später, z. B. beim Verlassen einer Ansicht:
  connection.removeEventListener("change", onChange);

  // Variante 2: AbortController, praktisch in Komponenten
  const controller = new AbortController();
  connection.addEventListener(
    "change",
    () => console.log("RTT jetzt:", connection.rtt, "ms"),
    { signal: controller.signal }
  );
  // Alle so registrierten Listener auf einmal entfernen:
  controller.abort();

  // on-Property zurücksetzen:
  connection.onchange = null;
}

// Wichtig · Fallstricke

Browser-Kompatibilität: navigator.connection und das change-Ereignis gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Samsung Internet sowie Android WebView). Firefox und Safari unterstützen die API nicht. Prüfe deshalb immer zuerst, ob navigator.connection vorhanden ist, und verwende sie nur zur schrittweisen Verbesserung (Progressive Enhancement).
Die API ist ein experimenteller Entwurf der WICG und kein W3C-Standard. Ihr Verhalten kann sich noch ändern.
downlink und rtt sind gerundete Schätzwerte. Chrome rundet rtt auf 25 ms und downlink auf 25 kbit/s, um Fingerprinting zu erschweren. Das Ereignis feuert deshalb nicht bei jeder kleinen Schwankung, sondern nur, wenn sich die gerundeten Werte ändern.
connection.type (z. B. "wifi", "cellular") ist auf Desktop-Browsern meist nicht verfügbar. Verlass dich lieber auf effectiveType.
Das Ereignis ist kein Ersatz für die Online-/Offline-Erkennung. Nutze dafür window.addEventListener("online"/"offline", …).
Die Eigenschaft onchange nimmt nur einen Handler auf, eine neue Zuweisung überschreibt den alten. Mit addEventListener kannst du mehrere Handler registrieren.
Die API ist auch in Web Workern verfügbar, dort über self.navigator.connection.
Datenschutz: Verbindungsdaten können zum Fingerprinting beitragen. Übertrage sie nicht ohne Grund an einen Server.

Siehe auch

Navigator.connection Navigator.onLine ScreenOrientation: change Notification: close Animation: cancel