NotRestoredReasonDetails.toJSON() — Methode · JavaScript-Referenz

Signatur

NotRestoredReasonDetails.prototype.toJSON()

Beschreibung

Die Methode toJSON() ist der Serializer der Schnittstelle NotRestoredReasonDetails. Sie liefert ein einfaches JavaScript-Objekt, das die Eigenschaft reason des Objekts enthält. Dieser String gibt an, warum eine Seite nicht aus dem Back/Forward-Cache (bfcache) wiederhergestellt wurde, zum Beispiel "unload-listener", "response-cache-control-no-store", "websocket" oder "masked".

NotRestoredReasonDetails-Objekte liegen im Array reasons eines NotRestoredReasons-Objekts. An dieses Objekt kommt man über PerformanceNavigationTiming.notRestoredReasons. Die Eigenschaften von Web-API-Objekten liegen als Getter auf dem Prototyp. Deshalb würde JSON.stringify() ohne toJSON() nur {} liefern. Weil JSON.stringify() die Methode toJSON() automatisch aufruft, kann man die Objekte direkt serialisieren.

Einsatzbereich: Analyse der bfcache-Nutzung im Produktivbetrieb. Man liest die Gründe aus, serialisiert sie und schickt sie zum Beispiel per navigator.sendBeacon() an einen eigenen Endpunkt. So erkennt man, welche Stellen im Code (etwa unload-Listener oder offene WebSockets) die sofortige Wiederherstellung der Seite verhindern.

Rückgabewert

Typ

Object

Beschreibung

Ein einfaches Objekt der Form { reason: string }, das die Eigenschaften des NotRestoredReasonDetails-Objekts abbildet.

Beispiele

Gründe für fehlende bfcache-Wiederherstellung auslesen

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

if (nrr) {
  for (const detail of nrr.reasons ?? []) {
    // toJSON() liefert ein einfaches Objekt
    console.log(detail.toJSON());
  }
} else {
  console.log('Keine Daten (Seite wiederhergestellt oder API nicht unterstützt)');
}

{ reason: "unload-listener" } { reason: "websocket" }

Direkt mit JSON.stringify serialisieren

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

// JSON.stringify ruft toJSON() automatisch auf
console.log(JSON.stringify(reasons));

// Zum Vergleich: ohne toJSON() wären die Getter nicht sichtbar
const plain = Object.assign({}, reasons[0]);
console.log(JSON.stringify(plain));

[{"reason":"response-cache-control-no-store"}] {}

Gründe per sendBeacon an einen Analyse-Endpunkt senden

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

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

  const payload = JSON.stringify({
    url: location.href,
    reasons: details.map((d) => d.toJSON())
  });

  navigator.sendBeacon('/analytics/bfcache', payload);
});

// Wichtig · Fallstricke

Experimentell und nur in Chromium verfügbar (ab Version 123). Firefox und Safari unterstützen notRestoredReasons nicht. Prüfen Sie deshalb immer mit optionaler Verkettung (?.), ob die Eigenschaft existiert.
notRestoredReasons ist null, wenn die Seite erfolgreich aus dem bfcache wiederhergestellt wurde oder es sich nicht um eine Vor-/Zurück-Navigation handelt.
Aus Datenschutzgründen können Gründe aus seitenübergreifenden (cross-origin) iframes als "masked" zusammengefasst sein. Der eigentliche Grund ist dann nicht sichtbar.
Die möglichen reason-Werte sind nicht vollständig standardisiert und können sich zwischen Browserversionen ändern. Werten Sie sie deshalb tolerant aus, zum Beispiel als freie Strings statt über eine feste Aufzählung.
toJSON() erzeugt keinen JSON-String, sondern ein Objekt. Für den String brauchen Sie JSON.stringify().

Siehe auch

JSON.stringify() NotRestoredReasons.toJSON() DOMRectReadOnly.toJSON() DOMMatrixReadOnly.toJSON() PressureRecord.toJSON()