HTMLMediaElement: suspend — Ereignis · JavaScript-Referenz

Signatur

mediaElement.addEventListener("suspend", handler)

Beschreibung

Das Ereignis suspend wird an einem <audio>- oder <video>-Element ausgelöst, wenn der Browser das Herunterladen von Mediendaten absichtlich anhält. Das ist kein Fehler. Typische Gründe: Es ist schon genug für die Wiedergabe gepuffert, das Attribut preload="metadata" oder preload="none" begrenzt das Vorladen, oder der Browser spart auf mobilen Geräten Bandbreite und Akku.

Zum Zeitpunkt des Ereignisses hat networkState meist den Wert HTMLMediaElement.NETWORK_IDLE (1). Die Ressource ist gewählt, wird aber gerade nicht geladen. Sobald wieder Daten gebraucht werden, zum Beispiel durch play() oder einen Sprung mit currentTime, lädt der Browser weiter und löst erneut progress-Ereignisse aus.

Das Ereignis lässt sich nicht abbrechen und steigt nicht im DOM auf (bubbles ist false). Du kannst es mit addEventListener("suspend", …) oder über die Eigenschaft onsuspend abfangen. Nützlich ist es für Lade-Anzeigen, zur Fehlersuche beim Puffern oder um eine Lade-Animation auszublenden, wenn der Browser das Vorladen beendet hat.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"suspend"`.
$handler Pflicht	(event: Event) => void		Die Callback-Funktion. Sie erhält ein normales `Event`-Objekt ohne zusätzliche Eigenschaften. Das Medienelement bekommst du über `event.target`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event, das nicht abbrechbar ist und nicht aufsteigt.

Beispiele

Unterbrochenes Laden protokollieren

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

video.addEventListener('suspend', (event) => {
  const el = event.target;
  const gepuffert = el.buffered.length
    ? el.buffered.end(el.buffered.length - 1).toFixed(1)
    : '0';
  console.log(`Laden pausiert – gepuffert bis ${gepuffert}s, networkState: ${el.networkState}`);
});

Laden pausiert – gepuffert bis 12.4s, networkState: 1

Lade-Anzeige mit der Eigenschaft onsuspend ausblenden

const audio = document.querySelector('audio');
const spinner = document.querySelector('#spinner');

audio.addEventListener('loadstart', () => {
  spinner.hidden = false;
});

// Alternative zu addEventListener: nur ein Handler möglich
audio.onsuspend = () => {
  spinner.hidden = true;
  console.log('Browser lädt vorerst nicht weiter.');
};

Browser lädt vorerst nicht weiter.

Listener mit AbortController wieder entfernen

const video = document.createElement('video');
video.preload = 'metadata';
video.src = 'https://example.com/film.mp4';

const controller = new AbortController();
const onSuspend = () => console.log('Nur Metadaten geladen, Download pausiert');

video.addEventListener('suspend', onSuspend, { signal: controller.signal });

// Später, z. B. beim Entfernen der Komponente:
video.addEventListener('loadedmetadata', () => {
  controller.abort(); // entspricht removeEventListener('suspend', onSuspend)
}, { once: true });

document.body.append(video);

Nur Metadaten geladen, Download pausiert

// Wichtig · Fallstricke

Kein Fehlerzeichen: suspend heißt nicht, dass etwas schiefgegangen ist. Für echte Probleme sind stalled (Daten kommen unerwartet nicht an), error und abort zuständig.
Uneinheitliches Verhalten: Wann und wie oft das Ereignis kommt, hängt vom Browser ab. Manche Browser lösen es mehrmals aus, manche bei vollständig gepufferten oder kleinen Dateien sofort nach loadedmetadata. Baue keine Programmlogik, die sich auf eine feste Reihenfolge verlässt.
Mobile Geräte: iOS Safari und Chrome für Android laden oft erst nach einer Nutzeraktion. Dann kommt suspend schon früh, auch bei preload="auto".
Das Ereignis steigt nicht auf. Ein Listener an einem Elternelement bekommt es also nur mit { capture: true } mit.
Die Unterstützung ist in allen modernen Browsern seit Jahren stabil vorhanden.

Siehe auch

HTMLMediaElement: stalled HTMLMediaElement: progress HTMLMediaElement: loadstart HTMLMediaElement: waiting HTMLMediaElement.networkState HTMLMediaElement.buffered HTMLMediaElement.preload