new PageTransitionEvent() — Methode · JavaScript-Referenz

Signatur

new PageTransitionEvent(type, options)

Beschreibung

Der Konstruktor PageTransitionEvent() erzeugt ein Ereignisobjekt vom Typ PageTransitionEvent. Der Browser erzeugt solche Objekte selbst, wenn eine Seite angezeigt (pageshow) oder verlassen (pagehide) wird. Dazu gehört auch das Wiederherstellen einer Seite aus dem Back/Forward-Cache (bfcache).

Die wichtigste Zusatzeigenschaft ist persisted. Sie zeigt an, ob die Seite aus dem bfcache stammt (pageshow) oder dort abgelegt werden kann (pagehide). Über das Optionsobjekt setzen Sie diesen Wert, wenn Sie das Ereignis selbst erzeugen.

Den Konstruktor brauchen Sie vor allem in Tests und zum Simulieren von Seitenwechseln, etwa um Ihre bfcache-Logik (Daten neu laden, Verbindungen wiederherstellen) ohne echte Navigation zu prüfen. Ein Ereignis, das Sie selbst mit dispatchEvent() auslösen, ist nicht vertrauenswürdig: isTrusted ist dann false.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"pageshow"` oder `"pagehide"`. Groß- und Kleinschreibung zählt.
$options	object	{}	Optionales Objekt. Es erbt die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standard `false`) und hat zusätzlich `persisted` (`boolean`, Standard `false`). `persisted` gibt an, ob die Seite aus dem bfcache stammt bzw. dort gespeichert wird.

Rückgabewert

Typ

PageTransitionEvent

Beschreibung

Ein neues PageTransitionEvent-Objekt. Seine Eigenschaft persisted hat den übergebenen Wert.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const event = new PageTransitionEvent('pageshow', { persisted: true });

console.log(event.type);      // Ereignisname
console.log(event.persisted); // aus dem bfcache?
console.log(event.isTrusted); // selbst erzeugt

pageshow true false

Seite aus dem bfcache erkennen

const refreshData = async () => {
  const res = await fetch('/api/warenkorb');
  const data = await res.json();
  document.querySelector('#anzahl').textContent = data.items.length;
};

window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    // Die Seite kommt aus dem bfcache, die Daten können veraltet sein
    console.log('Aus dem bfcache wiederhergestellt – Daten werden neu geladen');
    refreshData();
  }
});

Aus dem bfcache wiederhergestellt – Daten werden neu geladen

bfcache-Wiederherstellung im Test simulieren

let reloaded = false;

const onPageShow = (event) => {
  if (event.persisted) reloaded = true;
};
window.addEventListener('pageshow', onPageShow);

// Wiederherstellung aus dem bfcache nachstellen
window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));

console.log('Neu geladen:', reloaded);
window.removeEventListener('pageshow', onPageShow);

Neu geladen: true

pagehide statt unload verwenden

window.addEventListener('pagehide', (event) => {
  // Daten zuverlässig senden, bevor die Seite verlassen wird
  navigator.sendBeacon('/analytics', JSON.stringify({ persisted: event.persisted }));
  console.log(event.persisted ? 'Seite geht in den bfcache' : 'Seite wird verworfen');
});

Seite geht in den bfcache

// Wichtig · Fallstricke

Ein selbst ausgelöstes Ereignis hat isTrusted === false und navigiert nicht wirklich. Es ruft nur die registrierten Listener auf.
type ist ein Pflichtparameter. Ohne ihn wirft der Konstruktor einen TypeError.
Verwenden Sie pagehide statt unload: Ein unload-Listener verhindert in vielen Browsern, dass die Seite in den bfcache kommt. Chrome stellt unload außerdem schrittweise ein.
Das erste pageshow nach einem normalen Laden kommt nach load und hat persisted === false.
Kompatibilität: Der Konstruktor wird in allen aktuellen Browsern unterstützt (Chrome, Edge, Firefox, Safari). Der Internet Explorer unterstützt ihn nicht.

Siehe auch

Event new DeviceMotionEvent() new TransitionEvent() new AnimationEvent() new CompositionEvent()