PageTransitionEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface PageTransitionEvent extends Event

Beschreibung

PageTransitionEvent ist das Ereignisobjekt, das Handler der Events pageshow und pagehide am window erhalten. pageshow feuert, wenn ein Dokument angezeigt wird: nach dem ersten Laden (kurz nach load) oder bei der Wiederherstellung aus dem Back-/Forward-Cache. pagehide feuert, wenn der Nutzer die Seite verlässt.

Das Interface erweitert Event nur um die schreibgeschützte Eigenschaft persisted. Bei pageshow bedeutet true: Die Seite wurde aus dem bfcache wiederhergestellt, und JavaScript-Zustand, DOM und Timer sind noch vorhanden. Bei pagehide bedeutet true: Der Browser versucht, die Seite im bfcache abzulegen.

Wichtig ist das vor allem für den Back-/Forward-Cache. Bei einer Wiederherstellung aus dem Cache feuern DOMContentLoaded und load nicht erneut. Wer veraltete Daten auffrischen will (etwa Warenkorb, Login-Status oder Analytics-Seitenaufrufe), muss auf pageshow mit event.persisted === true reagieren.

Um Zustand beim Verlassen zu sichern, sind pagehide und visibilitychange die empfohlene Alternative zu unload und beforeunload. Diese beiden verhindern in vielen Browsern, dass die Seite in den bfcache kommt.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses beim Konstruktor `new PageTransitionEvent(type, options)`, üblicherweise `"pageshow"` oder `"pagehide"`.
$options	object	{}	Optionales Wörterbuch (erbt von `EventInit`: `bubbles`, `cancelable`, `composed`).
$options.persisted	boolean	false	Anfangswert der Eigenschaft `persisted`.

Rückgabewert

Typ

PageTransitionEvent

Beschreibung

Instanz mit der schreibgeschützten Eigenschaft persisted: boolean und allen Eigenschaften von Event.

Beispiele

Wiederherstellung aus dem bfcache erkennen

window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    console.log('Seite aus dem Back-/Forward-Cache wiederhergestellt');
  } else {
    console.log('Seite normal geladen');
  }
});

Seite normal geladen // nach Zurück-Navigation ggf.: Seite aus dem Back-/Forward-Cache wiederhergestellt

Veraltete Daten nach Zurück-Navigation auffrischen

const refreshCart = async () => {
  const res = await fetch('/api/cart', { cache: 'no-store' });
  const cart = await res.json();
  document.querySelector('#cart-count').textContent = cart.items.length;
};

const onPageShow = (event) => {
  // load feuert bei bfcache-Wiederherstellung nicht erneut
  if (event.persisted) {
    refreshCart();
  }
};

window.addEventListener('pageshow', onPageShow);

// Später bei Bedarf wieder entfernen
// window.removeEventListener('pageshow', onPageShow);

Zustand beim Verlassen sichern mit pagehide (onpagehide-Property)

window.onpagehide = (event) => {
  const draft = document.querySelector('#comment')?.value ?? '';
  sessionStorage.setItem('draft', draft);
  navigator.sendBeacon('/api/analytics', JSON.stringify({
    event: 'leave',
    cached: event.persisted
  }));
  console.log('pagehide, persisted =', event.persisted);
};

pagehide, persisted = true

Ereignis manuell erzeugen (z. B. für Tests)

const evt = new PageTransitionEvent('pageshow', { persisted: true });
console.log(evt instanceof Event, evt.type, evt.persisted);
window.dispatchEvent(evt);

true pageshow true

// Wichtig · Fallstricke

load vs. pageshow: Bei einer Wiederherstellung aus dem bfcache feuern load und DOMContentLoaded nicht. Logik, die bei jedem Anzeigen der Seite laufen muss, gehört in pageshow.
unload vermeiden: Registrierte unload-Handler (und teils beforeunload) schließen die Seite in vielen Browsern vom bfcache aus. Chrome stellt unload schrittweise ein. Nutze stattdessen pagehide oder visibilitychange.
persisted bei pagehide ist keine Garantie: Der Browser kann die Seite trotzdem aus dem Cache werfen, etwa bei Speicherknappheit, offenen Verbindungen oder Cache-Control: no-store.
Mobil: Wird ein Tab nur in den Hintergrund gelegt oder vom System beendet, feuert pagehide eventuell nicht. Für verlässliches Sichern zusätzlich visibilitychange (Zustand hidden) nutzen.
Seit Jahren in allen modernen Browsern verfügbar (Chrome, Firefox, Safari, Edge). Der Konstruktor ist in sehr alten Browsern nicht verfügbar.
Den Grund für einen bfcache-Ausschluss zeigen die Chrome DevTools (Application → Back/forward cache) oder die API PerformanceNavigationTiming.notRestoredReasons.

Siehe auch

Event Navigator.sendBeacon() ViewTransitionTypeSet TransitionEvent AnimationEvent