NetworkInformation.downlink — Eigenschaft · JavaScript-Referenz

Signatur

NetworkInformation.downlink

Beschreibung

Die Eigenschaft downlink der Schnittstelle NetworkInformation liefert die vom Browser geschätzte effektive Bandbreite in Megabit pro Sekunde (Mbit/s). Der Browser berechnet sie aus den Durchsatzwerten der zuletzt beobachteten Verbindungen, nicht aus der theoretischen Maximalgeschwindigkeit der Netzwerkhardware. Der Zugriff erfolgt über navigator.connection.downlink, in Web Workern über WorkerNavigator.connection.

Aus Datenschutzgründen wird der Wert gerundet, und zwar auf das nächste Vielfache von 25 kbit/s (also 0,025 Mbit/s). Außerdem ist er nach oben begrenzt: Chromium meldet höchstens 10 Mbit/s. Schnelle Glasfaser- und LAN-Anschlüsse lassen sich deshalb nicht von einer mittleren DSL-Leitung unterscheiden.

Typisch nutzt man die Eigenschaft für adaptives Laden: Bei geringer Bandbreite lädt man kleinere Bilder, verzichtet auf automatisch abspielende Videos oder verschiebt nicht benötigte Skripte. Ändert sich der Wert, löst das NetworkInformation-Objekt das Ereignis change aus. So kann eine Anwendung während der Laufzeit auf wechselnde Netzbedingungen reagieren.

Verwandt sind effectiveType (grobe Einstufung wie "4g" oder "3g"), rtt (geschätzte Umlaufzeit in Millisekunden) und saveData (der Nutzer hat den Datensparmodus aktiviert). Dieselbe Schätzung sendet der Browser auch als Client-Hint-Header Downlink an Server, die ihn angefordert haben.

Rückgabewert

Typ

number

Beschreibung

Geschätzte effektive Download-Bandbreite in Mbit/s als Gleitkommazahl, gerundet auf Vielfache von 0,025. In Chromium auf höchstens 10 begrenzt. 0 kann bedeuten, dass keine Verbindung besteht oder noch keine Messwerte vorliegen.

Beispiele

Bandbreite auslesen, mit Funktionsprüfung

const connection = navigator.connection;

if (connection && 'downlink' in connection) {
  console.log(`Geschätzte Bandbreite: ${connection.downlink} Mbit/s`);
} else {
  console.log('Network Information API wird nicht unterstützt');
}

Geschätzte Bandbreite: 8.55 Mbit/s

Bildqualität an die Bandbreite anpassen

const pickImageVariant = () => {
  const conn = navigator.connection;
  // Ohne API-Unterstützung: Standardqualität verwenden
  if (!conn) return 'medium';
  if (conn.saveData || conn.downlink < 1) return 'low';
  if (conn.downlink < 5) return 'medium';
  return 'high';
};

const img = document.createElement('img');
img.src = `/bilder/hero-${pickImageVariant()}.jpg`;
img.alt = 'Titelbild';
document.body.append(img);
console.log(img.src);

https://example.com/bilder/hero-high.jpg

Auf Bandbreitenänderungen reagieren (change-Ereignis)

const conn = navigator.connection;

const logDownlink = () => {
  console.log(`Neue Bandbreite: ${conn.downlink} Mbit/s (${conn.effectiveType}, RTT ${conn.rtt} ms)`);
};

if (conn) {
  conn.addEventListener('change', logDownlink);

  // Überwachung nach 60 Sekunden wieder beenden
  setTimeout(() => conn.removeEventListener('change', logDownlink), 60_000);
}

Neue Bandbreite: 1.45 Mbit/s (3g, RTT 300 ms)

Video-Autoplay nur bei ausreichender Bandbreite

const video = document.querySelector('video');
const conn = navigator.connection;

// Ohne API optimistisch annehmen, dass die Verbindung reicht
const fastEnough = !conn || (conn.downlink >= 2 && !conn.saveData);

if (video && fastEnough) {
  video.preload = 'auto';
  video.play().catch(() => console.log('Autoplay vom Browser blockiert'));
} else if (video) {
  video.preload = 'none';
  console.log('Autoplay wegen geringer Bandbreite deaktiviert');
}

Autoplay wegen geringer Bandbreite deaktiviert

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-Browser unterstützen die Eigenschaft (Chrome, Edge, Opera, Samsung Internet, Chrome für Android). Firefox und Safari bieten navigator.connection nicht an. Prüfen Sie deshalb immer vorher, ob die API vorhanden ist, und sehen Sie ein sinnvolles Standardverhalten vor.
Experimentelle API: Die Network Information API ist ein Entwurf der WICG und kein fertiger W3C-Standard. Einzelheiten können sich noch ändern.
Nur eine Schätzung: Der Wert stammt aus vergangenen Messungen, ist gerundet und in Chromium auf 10 Mbit/s begrenzt. Er eignet sich als grobe Orientierung, nicht als genaue Messung. Werte über 10 Mbit/s werden nie gemeldet.
Einheit: Die Angabe erfolgt in Megabit, nicht Megabyte pro Sekunde. Für Download-Zeiten durch 8 teilen.
Nicht mit downlinkMax verwechseln: downlinkMax war als theoretische Obergrenze der Verbindungstechnik gedacht und ist in Desktop-Browsern kaum verfügbar.
Datenschutz: Netzwerkmerkmale können zum Fingerprinting beitragen. Deshalb rundet der Browser die Werte, und manche Browser verzichten ganz auf die API.
Serverseitige Alternative: Mit dem Client-Hint Accept-CH: Downlink kann ein Server den Wert als HTTP-Header anfordern und Inhalte schon vor dem Ausliefern anpassen.

Siehe auch

Navigator.connection NetworkInformation.downlinkMax NetworkInformation.rtt NetworkInformation.saveData NetworkInformation.type