NotRestoredReasonDetails.reason — Eigenschaft · JavaScript-Referenz

Signatur

NotRestoredReasonDetails.reason

Beschreibung

Die Eigenschaft reason gehört zum Interface NotRestoredReasonDetails und enthält einen einzelnen, maschinenlesbaren Grund, warum der Browser eine Seite bei einer Zurück- oder Vorwärts-Navigation nicht aus dem Zurück-/Vorwärts-Cache (bfcache) wiederherstellen konnte. Typische Werte sind z. B. "unload-listener", "response-cache-control-no-store", "websocket", "lock", "broadcastchannel-message" oder "masked".

Man erreicht solche Objekte über den Navigations-Eintrag der Performance-API: performance.getEntriesByType("navigation")[0].notRestoredReasons liefert ein NotRestoredReasons-Objekt, dessen Array reasons aus NotRestoredReasonDetails-Instanzen besteht. Eingebettete Frames werden rekursiv über children abgebildet.

Die Eigenschaft ist vor allem für das Real User Monitoring nützlich: Man sammelt die Gründe im Feld, schickt sie an einen Analyse-Endpunkt und erkennt so, welche Funktionen (etwa unload-Handler oder offene WebSockets) die bfcache-Nutzung verhindern und damit schnelle Zurück-Navigationen ausbremsen.

Rückgabewert

Typ

string

Beschreibung

Ein String, der einen Blockierungsgrund bezeichnet, z. B. "unload-listener" oder "masked". Die Werteliste ist nicht abschließend und kann je nach Browser und Version wachsen.

Beispiele

Alle Gründe der Hauptseite auslesen

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

if (nav?.notRestoredReasons) {
  const reasons = nav.notRestoredReasons.reasons.map((detail) => detail.reason);
  console.log('bfcache blockiert durch:', reasons);
} else {
  console.log('Keine Zurück-/Vorwärts-Navigation oder API nicht unterstützt.');
}

bfcache blockiert durch: ['unload-listener', 'response-cache-control-no-store']

Gründe rekursiv inklusive iframes sammeln

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

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

┌───┬──────────────────────────────┬───────────────────┐ │ 0 │ https://example.com/ │ unload-listener │ │ 1 │ https://ads.example.net/ad │ masked │ └───┴──────────────────────────────┴───────────────────┘

Gründe per sendBeacon an ein Monitoring melden

window.addEventListener('pageshow', (event) => {
  if (event.persisted) return; // aus dem bfcache wiederhergestellt – alles gut

  const [nav] = performance.getEntriesByType('navigation');
  if (nav?.type !== 'back_forward' || !nav.notRestoredReasons) return;

  const payload = JSON.stringify({
    url: location.href,
    reasons: nav.notRestoredReasons.reasons.map((d) => d.reason)
  });
  navigator.sendBeacon('/analytics/bfcache', payload);
});

// Wichtig · Fallstricke

Kompatibilität: Bisher nur in Chromium-Browsern (Chrome/Edge ab 123) verfügbar. In Firefox und Safari fehlt notRestoredReasons. Deshalb immer mit optionaler Verkettung (?.) prüfen.
notRestoredReasons ist null, wenn es sich nicht um eine Navigation vom Typ back_forward handelt. Wurde die Seite tatsächlich aus dem bfcache geholt, entsteht gar kein neuer Navigations-Eintrag. Das erkennt man an pageshow mit event.persisted === true.
Datenschutz: Bei ursprungsübergreifenden (cross-origin) iframes werden die Gründe nicht offengelegt. Stattdessen erscheint der Sammelwert "masked". Er kann auch auftauchen, wenn der Browser Gründe aus anderen Ursachen verbirgt.
Die Werte sind nicht abschließend standardisiert und können sich je nach Browserversion ändern. Man sollte sie also nicht fest gegen eine Liste prüfen, sondern unbekannte Werte einfach mitprotokollieren.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden stillschweigend ignoriert oder lösen im Strict Mode einen Fehler aus.

Siehe auch

NotRestoredReasons.children NotRestoredReasons.reasons NotRestoredReasons.name NotRestoredReasons.src NotRestoredReasons.id