NavigationHistoryEntry.sameDocument — Eigenschaft · JavaScript-Referenz

Signatur

NavigationHistoryEntry.sameDocument

Beschreibung

Die schreibgeschützte Eigenschaft sameDocument eines NavigationHistoryEntry gibt an, ob der Eintrag auf dasselbe Document verweist wie der aktuelle Eintrag (navigation.currentEntry). Das ist der Fall, wenn der Eintrag durch eine Navigation innerhalb des Dokuments entstanden ist, etwa durch einen Fragment-Wechsel (#abschnitt), durch history.pushState() bzw. history.replaceState() oder durch eine abgefangene Navigation mit NavigateEvent.intercept().

In Single-Page-Anwendungen ist die Eigenschaft nützlich, um vor einem navigation.traverseTo() zu prüfen, ob ein Sprung im Verlauf ohne Neuladen der Seite gehen wird. So lässt sich entscheiden, ob ungesicherter Zustand gespeichert werden muss oder ob die App das Rendern selbst übernehmen kann. Außerdem kann man so die Verlaufs-Einträge filtern, die zur aktuellen App-Instanz gehören.

Der Wert bezieht sich immer auf das aktuell geladene Dokument. Einträge, die zu einem früher geladenen Dokument gehören, liefern false, auch wenn sie die gleiche URL haben. Wurde die Seite neu geladen, entsteht ein neues Document, und ältere Einträge gelten danach nicht mehr als gleiches Dokument.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Eintrag zum aktuellen Document gehört, sonst false. Für den Eintrag navigation.currentEntry ist der Wert immer true.

Beispiele

Aktuellen Eintrag und Verlauf prüfen

if ('navigation' in window) {
  // Der aktuelle Eintrag gehört immer zum aktuellen Dokument
  console.log(navigation.currentEntry.sameDocument);

  // Alle Einträge mit ihrem Status ausgeben
  for (const entry of navigation.entries()) {
    console.log(entry.index, entry.url, entry.sameDocument);
  }
}

true 0 https://example.com/ false 1 https://example.com/produkte true 2 https://example.com/produkte#details true

Vor dem Zurückspringen prüfen, ob die Seite neu geladen wird

const zurueckZu = async (key) => {
  const ziel = navigation.entries().find((e) => e.key === key);
  if (!ziel) return;

  if (!ziel.sameDocument) {
    // Die Seite wird neu geladen, deshalb Entwurf vorher sichern
    localStorage.setItem('entwurf', document.querySelector('#editor').value);
  }

  await navigation.traverseTo(key).finished;
  console.log('Navigation abgeschlossen:', navigation.currentEntry.url);
};

Navigation abgeschlossen: https://example.com/editor

Nur Einträge der aktuellen SPA-Sitzung anzeigen

const spaVerlauf = () =>
  navigation.entries()
    .filter((entry) => entry.sameDocument)
    .map((entry) => new URL(entry.url).pathname);

// Nach pushState-Navigationen innerhalb der App
history.pushState({}, '', '/konto');
history.pushState({}, '', '/konto/einstellungen');
console.log(spaVerlauf());

["/", "/konto", "/konto/einstellungen"]

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102. Firefox (ab 147) und Safari (ab 26.2) unterstützen sie erst seit Kurzem. Prüfen Sie vorher mit 'navigation' in window und bauen Sie für ältere Browser einen Ausweichweg über die History API ein.
Der Wert kann sich ändern: Wird die Seite neu geladen, ist ein vorher gespeicherter Eintrag danach sameDocument === false. Den Wert also nicht zwischenspeichern, sondern jedes Mal frisch abfragen.
Gleiche URL heißt nicht gleiches Dokument. Entscheidend ist die Dokument-Instanz, nicht die Adresse.
Nicht verwechseln mit NavigationDestination.sameDocument bzw. NavigateEvent: Dort beschreibt die Eigenschaft das Ziel einer laufenden Navigation, hier einen vorhandenen Verlaufs-Eintrag.
navigation.entries() enthält nur Einträge mit gleichem Ursprung aus demselben Browsing-Kontext. Fremde Ursprünge tauchen dort nicht auf.

Siehe auch

Navigation.entries() NavigationHistoryEntry.index NavigationHistoryEntry.id NavigationHistoryEntry.key NavigationHistoryEntry.url