Document: prerenderingchange — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("prerenderingchange", handler)

Beschreibung

Mit der Speculation Rules API kann ein Browser Seiten schon im Hintergrund vorrendern (prerendering), bevor der Nutzer sie aufruft. Die Seite lädt dabei vollständig, auch ihr JavaScript läuft. Navigiert der Nutzer dann tatsächlich dorthin, wird das vorgerenderte Dokument aktiviert, also angezeigt, und genau in diesem Moment löst der Browser am Document das Ereignis prerenderingchange aus.

Wichtig ist das Ereignis für alles, was erst ablaufen soll, wenn der Nutzer die Seite wirklich sieht: Seitenaufrufe in der Analyse zählen, Werbeeinblendungen, Animationen starten, Medien abspielen oder Benachrichtigungen anfordern. Ohne diese Unterscheidung würden bei vorgerenderten Seiten Aufrufe gezählt, die der Nutzer nie gesehen hat.

Üblich ist folgendes Muster: Mit document.prerendering prüfen, ob die Seite gerade vorgerendert wird. Wenn ja, die Aufgabe bis prerenderingchange zurückstellen, sonst sofort ausführen. Man kann den Listener per addEventListener registrieren oder über die Eigenschaft document.onprerenderingchange setzen. Das Ereignis ist ein einfaches Event ohne Zusatzdaten. Es steigt nicht auf (bubbles) und lässt sich nicht abbrechen.

Nach der Aktivierung liefert PerformanceNavigationTiming.activationStart die Zeit zwischen dem Start des Vorrenderns und der Aktivierung. So lassen sich Ladezeiten aus Sicht des Nutzers richtig messen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Ereignisses: `"prerenderingchange"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie erhält ein einfaches `Event`-Objekt ohne weitere Eigenschaften.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen für den Listener. Sinnvoll ist `{ once: true }`, denn ein Dokument wird höchstens einmal aktiviert.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event mit type === "prerenderingchange".

Beispiele

Analyse erst bei tatsächlicher Anzeige auslösen

const trackPageView = () => {
  console.log('Seitenaufruf gezählt:', location.pathname);
  // z. B. navigator.sendBeacon('/analytics', JSON.stringify({ path: location.pathname }));
};

if (document.prerendering) {
  // Seite wird vorgerendert – mit dem Zählen bis zur Aktivierung warten
  document.addEventListener('prerenderingchange', trackPageView, { once: true });
} else {
  trackPageView();
}

Seitenaufruf gezählt: /produkte

Wiederverwendbare Promise-Hilfsfunktion

const whenActivated = () =>
  new Promise((resolve) => {
    if (document.prerendering) {
      document.addEventListener('prerenderingchange', () => resolve(), { once: true });
    } else {
      resolve();
    }
  });

const init = async () => {
  await whenActivated();
  console.log('Seite ist sichtbar – starte Animationen und Video');
  document.querySelector('video')?.play();
};

init();

Seite ist sichtbar – starte Animationen und Video

Über die on-Property und mit Messung der Aktivierungszeit

document.onprerenderingchange = () => {
  const [nav] = performance.getEntriesByType('navigation');
  console.log('Aktiviert nach', Math.round(nav.activationStart), 'ms Vorrendern');
  // Handler wieder entfernen
  document.onprerenderingchange = null;
};

Aktiviert nach 2340 ms Vorrendern

Listener mit removeEventListener entfernen

const onActivate = () => console.log('Aktiviert');
document.addEventListener('prerenderingchange', onActivate);

// Wird die Funktion nicht mehr gebraucht (z. B. Komponente wird entfernt):
document.removeEventListener('prerenderingchange', onActivate);

// Wichtig · Fallstricke

Browser-Kompatibilität: Bisher nur in Chromium-Browsern (ab Chrome/Edge 108). Firefox und Safari kennen weder das Ereignis noch document.prerendering. Dort ist document.prerendering undefined und damit falsy, sodass das oben gezeigte Muster den Code einfach sofort ausführt. Eine eigene Erkennung der Funktion ist also nicht nötig.
Nicht mit visibilitychange verwechseln: Eine vorgerenderte Seite ist hidden. visibilitychange feuert auch beim Wechseln zwischen Tabs, prerenderingchange dagegen nur einmal, bei der Aktivierung.
Das Ereignis kommt höchstens einmal. Wird die vorgerenderte Seite verworfen, weil der Nutzer nicht dorthin navigiert, kommt es nie. Deshalb { once: true } verwenden und keine wichtigen Aufräumarbeiten davon abhängig machen.
Den Listener früh registrieren, am besten in einem Skript im <head>. Wer ihn zu spät anlegt, verpasst womöglich eine schon erfolgte Aktivierung. Deshalb immer zuerst document.prerendering prüfen.
Während des Vorrenderns werden manche APIs, die eine Nutzerinteraktion oder Berechtigungen brauchen (z. B. Notification.requestPermission(), Geolocation, alert()), zurückgehalten oder gesperrt. Solche Aufrufe gehören in den Handler.
Ladezeiten wie LCP oder FCP beim Vorrendern relativ zu activationStart messen, sonst fallen sie verfälscht aus.

Siehe auch

Document.prerendering Document: visibilitychange Document.visibilityState PerformanceNavigationTiming.activationStart EventTarget.addEventListener() Window: pageshow Element: MozMousePixelScroll