Document: readystatechange — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("readystatechange", handler)

Beschreibung

Das Ereignis readystatechange feuert am Document-Objekt immer dann, wenn sich die Eigenschaft document.readyState ändert. Sie durchläuft drei Zustände: "loading" (Dokument wird noch geparst), "interactive" (Parsen abgeschlossen, Unterressourcen wie Bilder, Stylesheets und iframes laden eventuell noch) und "complete" (Dokument samt allen Unterressourcen geladen).

Man registriert das Ereignis entweder per document.addEventListener("readystatechange", handler) oder über die Eigenschaft document.onreadystatechange = handler. Das Ereignis ist nicht abbrechbar und steigt nicht auf (bubbles: false); der Handler erhält ein einfaches Event-Objekt.

In der Praxis dient es als feinere Alternative zu DOMContentLoaded und load: Der Wechsel auf "interactive" erfolgt kurz vor DOMContentLoaded, der Wechsel auf "complete" kurz vor load am window. Damit lassen sich Initialisierungen früh anstoßen oder der Ladefortschritt protokollieren.

Wichtig: Wird ein Skript erst eingebunden, nachdem das Dokument bereits "complete" ist (z. B. nachgeladene Module), feuert das Ereignis nicht mehr. Prüfen Sie deshalb immer zuerst den aktuellen Wert von document.readyState.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"readystatechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Zustandsänderung aufgerufen wird. Den neuen Zustand liest man über `document.readyState` aus.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt (nicht abbrechbar, kein Bubbling).

Beispiele

Ladephasen protokollieren mit addEventListener

const start = performance.now();

console.log(`Start: ${document.readyState}`);

document.addEventListener('readystatechange', () => {
  const ms = Math.round(performance.now() - start);
  console.log(`readyState: ${document.readyState} (+${ms} ms)`);
});

document.addEventListener('DOMContentLoaded', () => console.log('DOMContentLoaded'));
window.addEventListener('load', () => console.log('window load'));

Start: loading readyState: interactive (+12 ms) DOMContentLoaded readyState: complete (+85 ms) window load

Robuste ready()-Hilfsfunktion (auch für spät geladene Skripte)

const whenReady = (state = 'interactive') => new Promise((resolve) => {
  const order = ['loading', 'interactive', 'complete'];
  const reached = () => order.indexOf(document.readyState) >= order.indexOf(state);

  if (reached()) return resolve();

  const onChange = () => {
    if (reached()) {
      document.removeEventListener('readystatechange', onChange);
      resolve();
    }
  };
  document.addEventListener('readystatechange', onChange);
});

const init = async () => {
  await whenReady('interactive');
  document.querySelector('#app')?.classList.add('ready');
  console.log('DOM bereit');

  await whenReady('complete');
  console.log('Alle Bilder und Stylesheets geladen');
};

init();

DOM bereit Alle Bilder und Stylesheets geladen

Variante mit der on-Property onreadystatechange

document.onreadystatechange = () => {
  if (document.readyState === 'complete') {
    document.getElementById('spinner')?.remove();
    console.log('Ladeindikator entfernt');
    // Handler wieder abmelden
    document.onreadystatechange = null;
  }
};

Ladeindikator entfernt

// Wichtig · Fallstricke

Kein Nachholen: Ist document.readyState bereits "complete", wenn der Listener registriert wird, feuert das Ereignis nie. Immer zuerst den aktuellen Zustand prüfen.
Reihenfolge: interactive kommt vor DOMContentLoaded, complete vor window-load. Skripte mit defer laufen zwischen interactive und DOMContentLoaded.
Nur ein on-Handler: Eine Zuweisung an document.onreadystatechange überschreibt vorherige Handler; für mehrere Listener addEventListener verwenden.
Verwechslungsgefahr: XMLHttpRequest besitzt ein gleichnamiges Ereignis mit numerischem readyState (0–4) – das ist eine andere API.
Kompatibilität: In allen modernen Browsern unterstützt. Sehr alte Internet-Explorer-Versionen feuerten das Ereignis auch an einzelnen Elementen und kannten den Zustand "loaded"; das ist heute irrelevant.

Siehe auch

Document.readyState EventTarget.addEventListener() CaptureController: zoomlevelchange HTMLInputElement: selectionchange Document: selectionchange