Navigation: currententrychange — Ereignis · JavaScript-Referenz

Signatur

navigation.addEventListener("currententrychange", handler)

Beschreibung

Das Ereignis currententrychange gehört zur Navigation API und wird am globalen Objekt window.navigation ausgelöst, sobald navigation.currentEntry auf einen anderen Verlaufseintrag zeigt. Das passiert bei Navigationen innerhalb desselben Dokuments (navigation.navigate(), history.pushState(), Fragment-Links, Vor/Zurück-Traversierung, abgefangene Navigationen per event.intercept()). Es feuert auch, wenn der Zustand des aktuellen Eintrags über navigation.updateCurrentEntry() ersetzt wird.

Der Handler bekommt ein NavigationCurrentEntryChangeEvent. Es hat zwei wichtige Eigenschaften: navigationType ("push", "replace", "reload", "traverse" oder null bei updateCurrentEntry()) und from, den NavigationHistoryEntry, der vorher aktuell war.

Typische Einsatzfälle: Analytics-Seitenaufrufe in Single-Page-Apps zählen, die Scroll- oder Formularposition des verlassenen Eintrags sichern, UI-Elemente wie die aktive Navigation oder den Dokumenttitel aktualisieren. Anders als navigate lässt sich dieses Ereignis nicht abbrechen. Es meldet nur eine Änderung, die bereits passiert ist.

Registrieren lässt sich der Handler per navigation.addEventListener("currententrychange", handler) oder über die Eigenschaft navigation.oncurrententrychange = handler.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Ereignisname, immer `"currententrychange"`.
$handler Pflicht	(event: NavigationCurrentEntryChangeEvent) => void		Callback, der das Ereignis erhält. Wichtig sind `event.navigationType` (`"push" \| "replace" \| "reload" \| "traverse" \| null`) und `event.from` (der vorherige `NavigationHistoryEntry`).
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen, z. B. `{ once: true }` oder `{ signal }`, um den Listener über einen `AbortController` zu entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein NavigationCurrentEntryChangeEvent, das nicht abbrechbar ist.

Beispiele

Seitenwechsel in einer SPA protokollieren

navigation.addEventListener("currententrychange", (event) => {
  const { navigationType, from } = event;
  const current = navigation.currentEntry;
  console.log(`Typ: ${navigationType}`);
  console.log(`Von: ${from.url}`);
  console.log(`Nach: ${current.url}`);
});

// Navigation innerhalb desselben Dokuments auslösen
navigation.navigate("#kontakt");

Typ: push Von: https://example.com/ Nach: https://example.com/#kontakt

Scrollposition des verlassenen Eintrags sichern (on-Property)

const scrollPositions = new Map();
let lastScrollY = window.scrollY;

window.addEventListener("scroll", () => {
  lastScrollY = window.scrollY;
}, { passive: true });

navigation.oncurrententrychange = (event) => {
  // Position dem vorherigen Eintrag zuordnen (key bleibt über Traversierungen stabil)
  scrollPositions.set(event.from.key, lastScrollY);
  console.log(`Gespeichert für ${event.from.key}:`, lastScrollY);
};

Gespeichert für 3f2a…: 840

Listener mit AbortController wieder entfernen

const controller = new AbortController();

navigation.addEventListener("currententrychange", (event) => {
  if (event.navigationType === null) {
    console.log("Nur der Zustand wurde aktualisiert:", navigation.currentEntry.getState());
  }
}, { signal: controller.signal });

navigation.updateCurrentEntry({ state: { filter: "neu" } });

// Später, z. B. beim Abbauen einer Komponente:
controller.abort();

Nur der Zustand wurde aktualisiert: { filter: "neu" }

Feature-Erkennung mit Fallback

if ("navigation" in window) {
  navigation.addEventListener("currententrychange", () => {
    document.title = `App – ${location.hash.slice(1) || "Start"}`;
  });
} else {
  // Fallback für Browser ohne Navigation API
  window.addEventListener("hashchange", () => {
    document.title = `App – ${location.hash.slice(1) || "Start"}`;
  });
}

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API gibt es in Chromium-Browsern seit Version 102. Firefox und Safari haben sie erst viel später eingeführt. Prüfen Sie deshalb immer mit "navigation" in window und sehen Sie für ältere Browser einen Fallback vor (popstate/hashchange).
Nur Navigationen im selben Dokument: Bei einer Navigation zu einem anderen Dokument wird die Seite entladen, dann feuert currententrychange im alten Dokument nicht.
Nicht abbrechbar: Wer eine Navigation verhindern oder umleiten will, muss das Ereignis navigate verwenden (preventDefault()/intercept()).
Zeitpunkt: Bei abgefangenen Navigationen feuert das Ereignis, sobald der Eintrag gewechselt hat. Das ist vor dem Abschluss des intercept()-Handlers. Wenn Inhalte fertig geladen sein müssen, warten Sie auf navigatesuccess oder das Promise navigation.transition.finished.
navigationType ist null, wenn nur updateCurrentEntry() aufgerufen wurde. Die URL hat sich dann nicht geändert.
event.from kann ein Eintrag sein, der danach aus dem Verlauf entfernt wird (etwa bei replace). Als stabilen Schlüssel für eigene Daten eignet sich entry.key, für einen einzelnen Eintrag entry.id.

Siehe auch

Navigation Navigation.currentEntry Navigation.updateCurrentEntry() NavigationCurrentEntryChangeEvent NavigationHistoryEntry