NotRestoredReasons.src — Eigenschaft · JavaScript-Referenz

Signatur

NotRestoredReasons.src

Beschreibung

Die Eigenschaft src des Interfaces NotRestoredReasons gibt den Pfad zur Quelle des <iframe> an, in dem das berichtete Dokument steckt, zum Beispiel "https://www.example.com/iframe.html". Sie entspricht dem src-Attribut des iframe-Elements.

Ein NotRestoredReasons-Objekt bekommst du über PerformanceNavigationTiming.notRestoredReasons. Es beschreibt, warum eine Seite nicht aus dem Back/Forward-Cache (bfcache) wiederhergestellt wurde. Das Objekt der obersten Ebene steht für das Hauptdokument, dort ist src null. Eingebettete Frames tauchen als Einträge im Array children auf, und bei diesen enthält src die Frame-Quelle.

Wofür das gut ist: Wenn ein iframe die Wiederherstellung aus dem bfcache blockiert, etwa ein Werbe- oder Chat-Widget mit unload-Handler, kannst du ihn über src (zusammen mit id und name) eindeutig erkennen. Das geht auch bei Frames von anderen Ursprüngen, deren url und reasons aus Datenschutzgründen verborgen sind.

Rückgabewert

Typ

string | null

Beschreibung

Der Wert des src-Attributs des zugehörigen <iframe> oder null, wenn der Bericht zum Hauptdokument gehört oder der Frame kein src-Attribut hat (z. B. bei srcdoc).

Beispiele

src der obersten Ebene und der Kind-Frames auslesen

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

if (report) {
  console.log('Hauptdokument src:', report.src);
  for (const child of report.children ?? []) {
    console.log('iframe src:', child.src);
  }
}

Hauptdokument src: null iframe src: https://www.example.com/iframe.html

Blockierende iframes nach dem Zurücknavigieren melden

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

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

  const blockingFrames = (report.children ?? [])
    .filter((child) => child.blocked)
    .map(({ src, id, name }) => ({ src, id, name }));

  if (blockingFrames.length > 0) {
    navigator.sendBeacon('/analytics/bfcache', JSON.stringify(blockingFrames));
  }
});

Verschachtelte Frames rekursiv durchlaufen

const collectSources = (node, depth = 0, out = []) => {
  out.push(`${'  '.repeat(depth)}${node.src ?? '(Hauptdokument)'}`);
  for (const child of node.children ?? []) {
    collectSources(child, depth + 1, out);
  }
  return out;
};

const [nav] = performance.getEntriesByType('navigation');
if (nav?.notRestoredReasons) {
  console.log(collectSources(nav.notRestoredReasons).join('\n'));
}

(Hauptdokument) https://ads.example.net/banner.html https://tracker.example.org/pixel.html

// Wichtig · Fallstricke

Browser-Unterstützung: Bisher nur in Chromium-Browsern (Chrome/Edge 123+). Firefox und Safari kennen notRestoredReasons nicht. Prüfe deshalb vorher, ob die Eigenschaft existiert, z. B. mit 'notRestoredReasons' in PerformanceNavigationTiming.prototype.
notRestoredReasons ist nur bei Navigationen vom Typ back_forward gefüllt, sonst ist der Wert null. Nach einer erfolgreichen Wiederherstellung aus dem bfcache (pageshow mit persisted === true) gibt es keinen neuen Eintrag.
src gibt den Wert des Attributs wieder, nicht unbedingt die tatsächlich geladene URL. Hat der Frame danach selbst weiternavigiert, steht die aktuelle Adresse in url. Die ist bei Frames von anderen Ursprüngen allerdings null.
Bei Frames von anderen Ursprüngen werden nur src, id, name und blocked offengelegt, die konkreten Gründe bleiben verborgen. Blockiert ein solcher Frame, steht im Elternobjekt oft nur der Grund "masked".
Beim Senden an Analyse-Dienste daran denken: src kann Abfrageparameter mit personenbezogenen Daten enthalten.

Siehe auch

NotRestoredReasons.url NotRestoredReasons.id NotRestoredReasons.name NotRestoredReasons.reasons NotRestoredReasons.children