NotRestoredReasons.toJSON() — Methode · JavaScript-Referenz

Signatur

NotRestoredReasons.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle NotRestoredReasons ist ein Serializer. Sie liefert ein einfaches JavaScript-Objekt mit den Eigenschaften children, id, name, reasons, src und url. Die Unterobjekte werden dabei ebenfalls in einfache Objekte umgewandelt: die Kind-Frames (NotRestoredReasons) und die Einträge vom Typ NotRestoredReasonDetails.

Ein NotRestoredReasons-Objekt erhältst du über PerformanceNavigationTiming.notRestoredReasons. Es erklärt, warum eine Seite bei einer Vor-/Zurück-Navigation nicht aus dem Back/Forward-Cache (bfcache) wiederhergestellt wurde, zum Beispiel wegen eines unload-Handlers oder einer offenen WebSocket-Verbindung.

In der Praxis rufst du toJSON() meist nicht selbst auf. JSON.stringify() ruft die Methode automatisch auf. Das ist wichtig, denn die Eigenschaften der Schnittstelle sind Getter auf dem Prototyp und würden ohne toJSON() nicht serialisiert. Typischer Einsatz: die Gründe per navigator.sendBeacon() an ein Analytics- oder RUM-Backend schicken und dort die häufigsten bfcache-Blocker auswerten.

Rückgabewert

Typ

object

Beschreibung

Ein einfaches Objekt mit children (Array von Objekten oder null), id, name, src, url (jeweils string oder null) und reasons (Array von { reason }-Objekten oder null).

Beispiele

Gründe für ein fehlgeschlagenes bfcache-Restore ausgeben

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

if (nav?.notRestoredReasons) {
  // toJSON() liefert ein einfaches Objekt
  const data = nav.notRestoredReasons.toJSON();
  console.log(data.url);
  console.log(data.reasons.map((r) => r.reason));
} else {
  console.log('Keine Vor-/Zurück-Navigation oder aus dem bfcache wiederhergestellt');
}

https://example.com/ ["unload-listener", "websocket"]

Mit JSON.stringify() an ein Analytics-Backend senden

const reportNotRestoredReasons = () => {
  const [nav] = performance.getEntriesByType('navigation');
  const nrr = nav?.notRestoredReasons;
  if (!nrr) return;

  // JSON.stringify ruft toJSON() automatisch auf
  const payload = JSON.stringify({
    type: nav.type,
    notRestoredReasons: nrr
  });
  navigator.sendBeacon('/analytics/bfcache', payload);
};

reportNotRestoredReasons();

Blockierende Frames rekursiv sammeln

const collectReasons = (node, path = 'main') => {
  const result = [];
  for (const { reason } of node.reasons ?? []) {
    result.push(`${path} (${node.src || node.url || '-'}): ${reason}`);
  }
  (node.children ?? []).forEach((child, i) => {
    result.push(...collectReasons(child, `${path} > ${child.id || child.name || 'iframe' + i}`));
  });
  return result;
};

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

main (https://example.com/): unload-listener main > ad-frame (https://ads.example.net/): masked

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die Methode gibt es ab Chrome/Edge 123. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher, ob die Funktion vorhanden ist, etwa mit 'notRestoredReasons' in PerformanceNavigationTiming.prototype.
notRestoredReasons ist null, wenn es keine Vor-/Zurück-Navigation war oder die Seite erfolgreich aus dem bfcache wiederhergestellt wurde. Prüfe das vor dem Aufruf, sonst kommt es zu einem TypeError.
Datenschutz: Bei ursprungsübergreifenden (cross-origin) iframes sind reasons und children null. Stattdessen erscheint im übergeordneten Frame höchstens der Grund "masked". Auch "masked" kann vorkommen, wenn der Browser Gründe aus Datenschutzgründen verbirgt.
Die Grund-Strings (z. B. "unload-listener", "websocket", "response-cache-control-no-store") sind nicht abschließend standardisiert und können sich zwischen Browserversionen ändern. Werte sie im Backend tolerant aus.
Das Ergebnis ist eine Momentaufnahme. Änderungen am ursprünglichen Objekt wirken sich darauf nicht aus.

Siehe auch

JSON.stringify() NotRestoredReasonDetails.toJSON() DOMRectReadOnly.toJSON() PressureRecord.toJSON() ContactAddress.toJSON()