Navigation.currentEntry — Eigenschaft · JavaScript-Referenz

Signatur

get Navigation.prototype.currentEntry

Beschreibung

Die schreibgeschützte Eigenschaft navigation.currentEntry der Navigation API liefert ein NavigationHistoryEntry-Objekt für den aktuellen Eintrag im Sitzungsverlauf des Dokuments. Über dieses Objekt kommen Sie an die URL (url), einen stabilen Schlüssel (key), eine eindeutige ID (id), die Position im Verlauf (index), die Angabe, ob der Eintrag zum selben Dokument gehört (sameDocument), und an den gespeicherten Zustand (getState()).

Gedacht ist die Eigenschaft vor allem für Single-Page-Anwendungen: Sie ersetzt das umständliche Paar location.href und history.state durch ein zusammenhängendes, gut strukturiertes Objekt. Anders als history.state wird der Zustand eines Eintrags nicht direkt verändert. Sie speichern ihn stattdessen über navigation.navigate(), navigation.reload() oder navigation.updateCurrentEntry({ state }).

Der zurückgegebene Eintrag ist eine Momentaufnahme. Sobald eine Navigation abgeschlossen ist, verweist currentEntry auf ein neues Objekt. Deshalb sollten Sie die Eigenschaft bei Bedarf jedes Mal neu abfragen oder auf das Ereignis currententrychange hören, statt einen alten Verweis weiterzuverwenden. Mit key lässt sich ein Verlaufsplatz dauerhaft erkennen, etwa um die Scroll-Position pro Eintrag zu speichern. id ändert sich dagegen auch bei replace-Navigationen.

Rückgabewert

Typ

NavigationHistoryEntry | null

Beschreibung

Der aktuelle Verlaufseintrag. null ist möglich, wenn die Navigation API für das Dokument nicht verfügbar ist, z. B. bei einem nicht voll aktiven Dokument oder dem anfänglichen about:blank.

Beispiele

Aktuellen Eintrag auslesen (mit Feature-Erkennung)

if ('navigation' in window && navigation.currentEntry) {
  const { url, key, id, index, sameDocument } = navigation.currentEntry;
  console.log({ url, key, id, index, sameDocument });
} else {
  console.log('Navigation API nicht verfügbar – Fallback auf location/history');
}

{ url: 'https://example.com/produkte', key: 'a1b2…', id: 'c3d4…', index: 2, sameDocument: true }

Zustand speichern und wieder lesen

// Filtereinstellungen einer Liste am aktuellen Eintrag ablegen
const saveFilter = (filter) => {
  navigation.updateCurrentEntry({
    state: { ...navigation.currentEntry.getState(), filter }
  });
};

saveFilter({ kategorie: 'buecher', sortierung: 'preis' });

// Später, z. B. nach Zurück/Vorwärts:
const state = navigation.currentEntry.getState();
console.log(state?.filter);

{ kategorie: 'buecher', sortierung: 'preis' }

Auf Wechsel des aktuellen Eintrags reagieren

const onEntryChange = (event) => {
  const entry = navigation.currentEntry;
  console.log(`Navigation (${event.navigationType}) von`,
    event.from.url, 'nach', entry.url);
  document.title = `Seite ${entry.index + 1}`;
};

navigation.addEventListener('currententrychange', onEntryChange);

// Aufräumen, z. B. beim Abbau einer Komponente
// navigation.removeEventListener('currententrychange', onEntryChange);

Navigation (push) von https://example.com/ nach https://example.com/kontakt

Scroll-Position pro Verlaufseintrag merken

const scrollPositions = new Map();

// Vor dem Verlassen die Position unter dem stabilen key speichern
navigation.addEventListener('navigate', () => {
  scrollPositions.set(navigation.currentEntry.key, window.scrollY);
});

navigation.addEventListener('currententrychange', () => {
  const y = scrollPositions.get(navigation.currentEntry.key) ?? 0;
  requestAnimationFrame(() => window.scrollTo(0, y));
});

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API gibt es in Chromium-Browsern seit Version 102. Firefox und Safari unterstützen sie erst seit neueren Versionen. Prüfen Sie deshalb immer mit 'navigation' in window und behalten Sie für ältere Browser einen Fallback über location und history.
Schreibgeschützt: Eine Zuweisung an navigation.currentEntry wird ignoriert (im Strict Mode gibt es einen TypeError). Den Zustand ändern Sie mit navigation.updateCurrentEntry().
Kann null sein: Verwenden Sie optionale Verkettung (navigation.currentEntry?.url), vor allem in iframes oder in sehr frühen Ladephasen.
Keine veralteten Verweise: Nach jeder Navigation gibt es ein neues Objekt. Ein zwischengespeicherter Eintrag zeigt nicht mehr auf den aktuellen Ort.
getState() liefert eine Kopie: Der Zustand wird mit dem Structured-Clone-Algorithmus kopiert. Änderungen am zurückgegebenen Objekt werden also nicht gespeichert. Funktionen und DOM-Knoten lassen sich nicht ablegen.
key und id: key bleibt bei replace-Navigationen gleich, id ändert sich. Für eigene Zuordnungen wie Scroll-Positionen oder Caches eignet sich deshalb meist key.
Einträge aus anderen Ursprüngen (Cross-Origin) sind nicht sichtbar. currentEntry bezieht sich nur auf den Verlauf des eigenen Dokuments bzw. Ursprungs.

Siehe auch

Navigation Navigation.entries() Navigation.navigate() History.state Navigation.canGoBack