HTMLMediaElement.networkState — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLMediaElement.networkState

Beschreibung

Die schreibgeschützte Eigenschaft networkState zeigt an, was ein Medienelement (<audio> oder <video>) gerade im Netzwerk tut. Der Wert ist eine der vier Konstanten, die auf HTMLMediaElement definiert sind:

NETWORK_EMPTY (0): Es gibt noch keine Daten. Das Element ist nicht initialisiert.
NETWORK_IDLE (1): Eine Medienressource ist ausgewählt, aber gerade wird nichts über das Netzwerk geladen.
NETWORK_LOADING (2): Der Browser lädt gerade Daten herunter.
NETWORK_NO_SOURCE (3): Es wurde keine passende Quelle gefunden, zum Beispiel wegen eines ungültigen Pfads oder eines nicht unterstützten Formats.

Mit dieser Eigenschaft kannst du Ladeanzeigen, eigene Player-Oberflächen oder die Fehlerdiagnose umsetzen. Frag sie am besten in Ereignissen wie loadstart, progress, suspend, stalled oder error ab. Ständiges Abfragen per Polling ist nicht nötig.

networkState beschreibt nur den Netzwerk-Status. Ob genug Daten zum Abspielen da sind, sagt dir readyState. Ein Element kann also auf NETWORK_IDLE stehen und trotzdem schon vollständig abspielbar sein, etwa weil der Browser das Laden bewusst pausiert hat (Ereignis suspend).

Rückgabewert

Typ

number

Beschreibung

Eine der Konstanten 0 (NETWORK_EMPTY), 1 (NETWORK_IDLE), 2 (NETWORK_LOADING) oder 3 (NETWORK_NO_SOURCE).

Beispiele

Netzwerkstatus als lesbaren Text ausgeben

const video = document.querySelector('video');

const statusText = (el) => {
  switch (el.networkState) {
    case HTMLMediaElement.NETWORK_EMPTY: return 'leer (nicht initialisiert)';
    case HTMLMediaElement.NETWORK_IDLE: return 'untätig (Quelle gewählt, kein Download)';
    case HTMLMediaElement.NETWORK_LOADING: return 'lädt gerade';
    case HTMLMediaElement.NETWORK_NO_SOURCE: return 'keine passende Quelle';
    default: return 'unbekannt';
  }
};

console.log(`Netzwerkstatus: ${statusText(video)}`);

Netzwerkstatus: lädt gerade

Ladeanzeige über Ereignisse steuern

const video = document.querySelector('#player');
const spinner = document.querySelector('#spinner');

const updateSpinner = () => {
  const loading = video.networkState === video.NETWORK_LOADING;
  spinner.hidden = !loading;
  console.log(`networkState=${video.networkState}, Spinner sichtbar: ${loading}`);
};

['loadstart', 'progress', 'suspend', 'stalled', 'loadeddata'].forEach((type) =>
  video.addEventListener(type, updateSpinner)
);

networkState=2, Spinner sichtbar: true networkState=1, Spinner sichtbar: false

Fehlende oder nicht unterstützte Quelle erkennen

const audio = new Audio();
audio.src = '/media/podcast-folge.xyz'; // nicht unterstütztes Format

audio.addEventListener('error', () => {
  if (audio.networkState === HTMLMediaElement.NETWORK_NO_SOURCE) {
    console.warn('Keine abspielbare Quelle gefunden – Fallback wird geladen.');
    audio.src = '/media/podcast-folge.mp3';
  }
});

console.log(audio.networkState); // direkt nach dem Setzen meist 2 oder 0

2 Keine abspielbare Quelle gefunden – Fallback wird geladen.

// Wichtig · Fallstricke

Schreibgeschützt: Wenn du networkState einen Wert zuweist, passiert nichts. Im Strict Mode gibt es dabei keinen Fehler, weil nur ein Getter existiert. Die Zuweisung wird einfach ignoriert.
Konstanten statt fester Zahlen: Vergleiche besser mit HTMLMediaElement.NETWORK_LOADING usw. als mit 2. Das macht den Code lesbarer.
Nicht mit readyState verwechseln: NETWORK_IDLE heißt nicht, dass das Laden fertig ist. Der Browser kann den Download pausieren (Ereignis suspend), zum Beispiel bei preload="none" oder preload="metadata".
Fehler bei <source>-Kindern: Wenn keine Quelle passt, wird das error-Ereignis am letzten <source>-Element ausgelöst und nicht am Medienelement selbst. Prüfe networkState === NETWORK_NO_SOURCE deshalb gegebenenfalls in einem Listener am <source>-Element.
Kompatibilität: Die Eigenschaft wird seit vielen Jahren von allen modernen Browsern unterstützt. Wann genau ein Zustand wechselt (etwa zwischen IDLE und LOADING), kann sich aber je nach Browser und Puffer-Strategie unterscheiden. Verlass dich daher nicht auf exakte Übergangszeitpunkte.

Siehe auch

HTMLMediaElement.readyState HTMLMediaElement.error HTMLMediaElement.load() HTMLMediaElement.preload HTMLMediaElement