NotRestoredReasonDetails — Schnittstelle · JavaScript-Referenz

Signatur

interface NotRestoredReasonDetails

Beschreibung

NotRestoredReasonDetails gehört zur Performance API und steht für genau einen Grund, warum der Browser eine Seite nicht aus dem Back-/Forward-Cache (bfcache) wiederhergestellt hat. Man erzeugt solche Objekte nicht selbst. Man bekommt sie über das Array reasons eines NotRestoredReasons-Objekts, das die Eigenschaft PerformanceNavigationTiming.notRestoredReasons liefert.

Die Schnittstelle ist klein:

reason (nur lesbar, string): der Grund, zum Beispiel "unload-listener", "response-cache-control-no-store", "websocket", "broadcastchannel", "lock" oder "masked".
toJSON(): gibt ein einfaches Objekt { reason } zurück. Damit kann man die Daten mit JSON.stringify() in Text umwandeln und an ein Analyse-Backend senden.

Nützlich ist das vor allem beim Real User Monitoring. So erfährt man, welche Funktionen einer Seite (etwa unload-Listener, offene WebSockets oder Cache-Control: no-store) die sofortige Wiederherstellung beim Zurück-Navigieren verhindern. Wer diese Ursachen behebt, macht Navigationen deutlich schneller.

Die Gründe werden als Baum geliefert. Jedes NotRestoredReasons-Objekt steht für ein Dokument oder einen <iframe> und hat eigene reasons sowie children. Deshalb muss man den Baum rekursiv durchlaufen, um alle NotRestoredReasonDetails einzusammeln.

Parameter

Name	Typ	Default	Beschreibung
$reason Pflicht	string		Nur lesbare Eigenschaft (kein Konstruktor-Parameter). Enthält den Grund als Zeichenkette, z. B. `"unload-listener"` oder `"masked"`.
$toJSON()	() => { reason: string }		Methode, die das Objekt als einfaches JSON-Objekt zurückgibt. `JSON.stringify()` ruft sie automatisch auf.

Rückgabewert

Typ

NotRestoredReasonDetails

Beschreibung

Es gibt keinen öffentlichen Konstruktor. Instanzen stehen im Array NotRestoredReasons.reasons. Ist die Seite nicht betroffen, ist dieses Array leer oder null.

Beispiele

Gründe der aktuellen Navigation auslesen

const [nav] = performance.getEntriesByType('navigation');

if (nav && 'notRestoredReasons' in nav) {
  const nrr = nav.notRestoredReasons;
  if (nrr === null) {
    console.log('Keine bfcache-Informationen (keine Vor-/Zurück-Navigation).');
  } else {
    // nrr.reasons ist ein Array von NotRestoredReasonDetails
    for (const detail of nrr.reasons ?? []) {
      console.log('Grund:', detail.reason);
    }
  }
} else {
  console.log('notRestoredReasons wird nicht unterstützt.');
}

Grund: unload-listener Grund: response-cache-control-no-store

Alle Gründe inklusive iframes rekursiv sammeln

const collectReasons = (node, path = 'main') => {
  if (!node) return [];
  const own = (node.reasons ?? []).map((d) => ({ frame: node.src || node.url || path, reason: d.reason }));
  const nested = (node.children ?? []).flatMap((child, i) =>
    collectReasons(child, `${path} > iframe[${i}]`)
  );
  return [...own, ...nested];
};

const [nav] = performance.getEntriesByType('navigation');
console.table(collectReasons(nav?.notRestoredReasons));

┌─────────┬───────────────────────────────┬───────────────────┐ │ (index) │ frame │ reason │ ├─────────┼───────────────────────────────┼───────────────────┤ │ 0 │ https://example.com/ │ unload-listener │ │ 1 │ https://example.com/chat.html │ websocket │ └─────────┴───────────────────────────────┴───────────────────┘

Gründe per toJSON() an das Monitoring senden

window.addEventListener('pageshow', (event) => {
  // persisted === true bedeutet: Seite kam aus dem bfcache, also gibt es nichts zu melden
  if (event.persisted) return;

  const [nav] = performance.getEntriesByType('navigation');
  const details = nav?.notRestoredReasons?.reasons ?? [];
  if (details.length === 0) return;

  // JSON.stringify ruft NotRestoredReasonDetails.toJSON() automatisch auf
  const payload = JSON.stringify({ page: location.pathname, reasons: details });
  navigator.sendBeacon('/analytics/bfcache', payload);
  console.log(payload);
});

{"page":"/produkte","reasons":[{"reason":"unload-listener"}]}

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher gibt es die Schnittstelle nur in Chromium-Browsern (Chrome/Edge ab 123). Deshalb vor der Nutzung immer mit 'notRestoredReasons' in nav prüfen, ob sie vorhanden ist.

notRestoredReasons ist null, wenn die Navigation keine Vor-/Zurück-Navigation war (Navigationstyp nicht back_forward).
Bei ursprungsfremden (cross-origin) iframes werden die genauen Gründe aus Datenschutzgründen verborgen. Stattdessen erscheint der Grund "masked", auch mit src/url auf null.
Die möglichen Werte von reason sind nicht abschließend festgelegt und können sich je nach Browserversion ändern. Unbekannte Werte sollte man daher nicht als Fehler behandeln.
Die Gründe beziehen sich auf den vorherigen Besuch der Seite. Man liest sie also erst beim erneuten Laden nach einer Zurück-Navigation aus, nicht beim Verlassen der Seite.
Häufige Ursachen, die man leicht beheben kann: unload-Listener (besser pagehide verwenden), offene WebSocket- oder IndexedDB-Verbindungen (in pagehide schließen) und Cache-Control: no-store.

Siehe auch

NotRestoredReasons ScreenDetails DOMRectReadOnly DirectoryReaderSync ScreenDetailed