NavigationHistoryEntry — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigationHistoryEntry extends EventTarget

Beschreibung

Das Interface NavigationHistoryEntry gehört zur Navigation API und steht für genau einen Eintrag im Sitzungsverlauf des aktuellen Dokuments bzw. derselben Origin. Instanzen erzeugt man nicht selbst. Man bekommt sie über navigation.currentEntry, navigation.entries() oder über NavigateEvent.destination bzw. die Eigenschaft from im Ereignis currententrychange.

Jeder Eintrag hat folgende Eigenschaften:

url: die absolute URL des Eintrags (kann null sein, wenn eine no-referrer-Policy gilt).
key: ein eindeutiger Schlüssel für die Position im Verlauf. Er bleibt bei replace-Navigationen erhalten und eignet sich für navigation.traverseTo(key).
id: eine eindeutige ID für genau diesen Eintrag. Sie ändert sich bei jedem Ersetzen und eignet sich z. B. als Cache-Schlüssel.
index: die Position in navigation.entries(), oder -1, wenn der Eintrag nicht mehr im Verlauf ist.
sameDocument: true, wenn der Eintrag zum aktuellen Dokument gehört (z. B. Fragment- oder pushState-Navigation).

Dazu kommt die Methode getState(). Sie liefert eine per structured clone erzeugte Kopie des Zustands, der bei navigation.navigate(), reload() oder updateCurrentEntry() gespeichert wurde. Wird ein Eintrag aus dem Verlauf entfernt, feuert das Ereignis dispose (auch als ondispose). Damit lassen sich zugehörige Ressourcen wie Caches oder Scrollpositionen aufräumen.

Im Vergleich zur alten History API mit history.state und popstate ist NavigationHistoryEntry deutlich aussagekräftiger. Man kann alle Einträge der eigenen Origin auflisten und jedem Eintrag eigenen Zustand zuordnen. Außerdem kann man gezielt per Schlüssel springen. Das ist vor allem für Routing in Single-Page-Apps nützlich.

Rückgabewert

Typ

NavigationHistoryEntry

Beschreibung

Man bekommt Instanzen über navigation.currentEntry, navigation.entries(), NavigateEvent.destination (als NavigationDestination) oder NavigationCurrentEntryChangeEvent.from. getState() gibt any zurück, also eine Kopie des gespeicherten Zustands, oder undefined.

Beispiele

Aktuellen Eintrag auslesen

if ('navigation' in window) {
  const entry = navigation.currentEntry;
  console.log(entry.url);
  console.log(entry.index, entry.sameDocument);
  console.log('key:', entry.key, 'id:', entry.id);
} else {
  console.warn('Navigation API wird nicht unterstützt');
}

https://example.com/produkte 0 true key: 3b9f… id: a71c…

Zustand speichern und mit getState() lesen

// Filterzustand im aktuellen Eintrag ablegen, ohne neu zu navigieren
navigation.updateCurrentEntry({
  state: { filter: 'bücher', seite: 2 }
});

const state = navigation.currentEntry.getState();
console.log(state.filter, state.seite);

// getState() liefert eine Kopie: Änderungen daran werden nicht gespeichert
state.seite = 99;
console.log(navigation.currentEntry.getState().seite);

bücher 2 2

Verlauf auflisten und per key zurückspringen

const entries = navigation.entries();
entries.forEach((e) => console.log(e.index, e.url));

// Zum ersten Eintrag der Startseite springen
const home = entries.find((e) => new URL(e.url).pathname === '/');
if (home) {
  await navigation.traverseTo(home.key).finished;
  console.log('Zurück auf der Startseite');
}

0 https://example.com/ 1 https://example.com/produkte 2 https://example.com/produkte/42 Zurück auf der Startseite

Aufräumen beim dispose-Ereignis

const cache = new Map();

const remember = (entry, data) => {
  cache.set(entry.id, data);
  // Feuert, wenn der Eintrag endgültig aus dem Verlauf entfernt wird
  entry.addEventListener('dispose', () => {
    cache.delete(entry.id);
    console.log('Cache für', entry.url, 'entfernt');
  }, { once: true });
  // Alternativ: entry.ondispose = () => cache.delete(entry.id);
};

remember(navigation.currentEntry, { scrollY: window.scrollY });

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) unterstützen die API seit Version 102. Firefox unterstützt sie seit Version 147, Safari seit 26.2. Damit ist sie erst seit Anfang 2026 Baseline, in älteren Versionen fehlt sie. Prüfe deshalb immer mit 'navigation' in window und behalte die History API als Rückfalllösung.
key und id haben unterschiedliche Aufgaben: key steht für die Position im Verlauf und bleibt bei replace gleich. id steht für den konkreten Eintrag und ändert sich bei jedem Ersetzen. Für traverseTo() nimmst du key, für Caches pro Eintrag id.
getState() gibt eine Kopie zurück. Wenn du das Ergebnis veränderst, wird nichts gespeichert, dafür brauchst du navigation.updateCurrentEntry(). Der Zustand muss per structured clone kopierbar sein: Funktionen oder DOM-Knoten lösen einen DataCloneError aus.
navigation.entries() enthält nur Einträge derselben Origin im aktuellen Browsing-Kontext. Einträge fremder Origins sind aus Datenschutzgründen nicht sichtbar.
Ist ein Eintrag nicht mehr im Verlauf, z. B. weil nach einem Zurückspringen neu navigiert wurde, liefert index den Wert -1.
Der Zustand aus der Navigation API ist unabhängig von history.state. Beide nebeneinander zu verwenden führt leicht zu Verwirrung.

Siehe auch

Navigation Navigation.entries() History NavigationDestination NavigationActivation