NotRestoredReasons.name — Eigenschaft · JavaScript-Referenz

Signatur

NotRestoredReasons.name

Beschreibung

Die schreibgeschützte Eigenschaft name der Schnittstelle NotRestoredReasons enthält den Wert des name-Attributs des <iframe>-Elements, in dem das betreffende Dokument geladen wurde. Bei <iframe name="werbung"> ist das zum Beispiel "werbung". Für das Dokument der obersten Ebene, also das Hauptdokument, ist der Wert null.

Die Eigenschaft gehört zur API „Back/Forward Cache Not Restored Reasons“. Über PerformanceNavigationTiming.notRestoredReasons erfahren Sie, warum eine Seite beim Vor- oder Zurücknavigieren nicht aus dem Back/Forward-Cache (bfcache) wiederhergestellt wurde. Das Ergebnis ist ein Baum aus NotRestoredReasons-Objekten: Der Wurzelknoten steht für das Hauptdokument, die Einträge in children stehen für eingebettete Frames.

Mit name (zusammen mit id, src und url) finden Sie heraus, welches iframe die Wiederherstellung blockiert hat. Das ist praktisch, wenn eine Seite viele Frames von Drittanbietern einbindet, zum Beispiel für Werbung, Chat-Widgets oder Analysedienste, und Sie deren Einfluss auf den bfcache in Ihrem Monitoring (RUM) auswerten möchten.

Rückgabewert

Typ

string | null

Beschreibung

Der Wert des name-Attributs des einbettenden <iframe>. null beim Dokument der obersten Ebene. Hat das iframe kein name-Attribut, ist der Wert laut MDN ebenfalls null; manche Browser liefern hier möglicherweise einen leeren String.

Beispiele

Name des Hauptdokuments und der direkten Frames auslesen

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

if (reasons) {
  // Das Hauptdokument hat keinen iframe-Namen
  console.log('Top-Level:', reasons.name);
  for (const child of reasons.children ?? []) {
    console.log('Frame:', child.name, child.src);
  }
} else {
  console.log('Keine Daten (keine Zurück/Vor-Navigation oder nicht unterstützt)');
}

Top-Level: null Frame: werbung https://ads.example.com/banner.html

Blockierende iframes rekursiv per Name finden

const findBlockingFrames = (node, result = []) => {
  if (node.name !== null && node.reasons?.length) {
    result.push({
      name: node.name,
      src: node.src,
      reasons: node.reasons.map((r) => r.reason)
    });
  }
  for (const child of node.children ?? []) {
    findBlockingFrames(child, result);
  }
  return result;
};

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

┌───┬───────────┬──────────────────────────────┬──────────────────┐ │ │ name │ src │ reasons │ ├───┼───────────┼──────────────────────────────┼──────────────────┤ │ 0 │ 'chat' │ 'https://chat.example/w.html'│ ['unload-listener'] │ └───┴───────────┴──────────────────────────────┴──────────────────┘

Frame-Namen per sendBeacon an das Monitoring schicken

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 frameNames = (nav.notRestoredReasons.children ?? [])
    .map((c) => c.name ?? '(ohne Namen)');

  navigator.sendBeacon('/rum/bfcache', JSON.stringify({
    page: location.pathname,
    frames: frameNames
  }));
});

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist experimentell und bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab 123). Prüfen Sie daher vorher mit 'notRestoredReasons' in PerformanceNavigationTiming.prototype, ob sie unterstützt wird.
Werte sind nur bei Zurück/Vor-Navigationen gefüllt: Bei anderen Navigationsarten ist notRestoredReasons null, deshalb gibt es dann auch kein name.
Frames anderer Herkunft (Cross-Origin): name, id und src kommen aus den Attributen im Elterndokument und sind deshalb auch hier sichtbar. url und die Gründe im Detail werden dagegen aus Datenschutzgründen verborgen. Stattdessen erscheint im Elternknoten gegebenenfalls ein zusammengefasster Grund wie "masked".
Das name-Attribut ist nicht eindeutig. Mehrere iframes können denselben Namen haben. Für eine sichere Zuordnung kombinieren Sie name am besten mit id und src.
Maßgeblich ist der Attributwert zum Zeitpunkt der Navigation. Spätere Änderungen an iframe.name oder window.name im Frame werden nicht rückwirkend berücksichtigt.

Siehe auch

NotRestoredReasons.id NotRestoredReasons.src NotRestoredReasons.url NotRestoredReasons.reasons NotRestoredReasons.children