NavigationCurrentEntryChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigationCurrentEntryChangeEvent extends Event

Beschreibung

NavigationCurrentEntryChangeEvent gehört zur Navigation API. Ein Objekt dieses Typs wird an Listener des Ereignisses currententrychange auf dem globalen navigation-Objekt übergeben. Das Ereignis wird ausgelöst, sobald sich navigation.currentEntry geändert hat. Das passiert bei einer Navigation innerhalb desselben Dokuments (z. B. über navigation.navigate(), history.pushState() oder Vor/Zurück), aber auch bei navigation.updateCurrentEntry().

Das Interface erbt von Event und bringt zwei eigene, schreibgeschützte Eigenschaften mit:

from: der NavigationHistoryEntry, der vor der Änderung aktuell war.
navigationType: die Art der Navigation, die zur Änderung geführt hat, also "push", "replace", "reload" oder "traverse". Bei updateCurrentEntry() ist der Wert null.

Das Ereignis eignet sich gut für Aufgaben, die nach einem Wechsel des Eintrags laufen sollen: Analytics-Seitenaufrufe, das Speichern der Scroll-Position oder eines UI-Zustands für den alten Eintrag, oder das Aktualisieren von Breadcrumbs. Um Navigationen abzufangen oder umzulenken, ist dagegen das navigate-Ereignis mit NavigateEvent.intercept() gedacht. currententrychange lässt sich nicht abbrechen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor `new NavigationCurrentEntryChangeEvent(type, options)`: der Ereignisname, üblicherweise `"currententrychange"`.
$options Pflicht	object		Initialisierungsobjekt. Es erbt die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`).
$options.from Pflicht	NavigationHistoryEntry		Der Eintrag, von dem aus navigiert wurde. Wird zur Eigenschaft `from`.
$options.navigationType	"push"\|"replace"\|"reload"\|"traverse"\|null	null	Die Art der Navigation. Wird zur Eigenschaft `navigationType`.

Rückgabewert

Typ

NavigationCurrentEntryChangeEvent

Beschreibung

Beim Konstruktoraufruf eine neue Ereignisinstanz. Im Normalfall erzeugt der Browser das Objekt selbst und übergibt es an den Listener.

Beispiele

Seitenwechsel protokollieren mit addEventListener

if ('navigation' in window) {
  navigation.addEventListener('currententrychange', (event) => {
    const von = event.from.url;
    const nach = navigation.currentEntry.url;
    console.log(`Typ: ${event.navigationType}, von ${von} nach ${nach}`);
  });

  // Navigation im selben Dokument auslösen
  history.pushState({}, '', '/produkte');
}

Typ: push, von https://example.com/ nach https://example.com/produkte

Zustand des alten Eintrags sichern (on-Property)

// Scroll-Position des verlassenen Eintrags merken
const scrollPositionen = new Map();

navigation.oncurrententrychange = (event) => {
  if (event.navigationType === null) return; // nur updateCurrentEntry()
  scrollPositionen.set(event.from.key, window.scrollY);
  console.log('Gespeichert für', event.from.key);
};

Gespeichert für 3f2a9c1e-…

Listener wieder entfernen

const beiWechsel = (event) => {
  console.log('Einmaliger Wechsel:', event.navigationType);
  navigation.removeEventListener('currententrychange', beiWechsel);
};

navigation.addEventListener('currententrychange', beiWechsel);
navigation.navigate('#details');

Einmaliger Wechsel: push

Ereignis manuell erzeugen (z. B. für Tests)

const ev = new NavigationCurrentEntryChangeEvent('currententrychange', {
  from: navigation.currentEntry,
  navigationType: 'replace'
});

console.log(ev.type, ev.navigationType, ev.from === navigation.currentEntry);

currententrychange replace true

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API gibt es seit Chromium 102. Firefox und Safari haben sie erst in neueren Versionen eingeführt. Prüfen Sie die Unterstützung mit 'navigation' in window und behalten Sie für ältere Browser einen Fallback über popstate oder die History API bei.
Das Ereignis wird erst nach dem Wechsel ausgelöst. Beim Aufruf enthält navigation.currentEntry schon den neuen Eintrag, und event.from verweist auf den alten.
navigationType ist null, wenn nur navigation.updateCurrentEntry() den Zustand geändert hat. Prüfen Sie das, bevor Sie etwa einen Seitenaufruf zählen.
Das Ereignis lässt sich nicht abbrechen. Ein preventDefault() hat keine Wirkung. Zum Abfangen oder Blockieren einer Navigation verwenden Sie das navigate-Ereignis.
Bei einem vollständigen Dokumentwechsel (neue Seite wird geladen) wird das Ereignis im alten Dokument nicht ausgelöst. Es gilt nur für Navigationen innerhalb desselben Dokuments.
Wenn die Navigation zu einem Eintrag eines anderen Ursprungs führt, liefert event.from.url unter Umständen null, etwa bei noreferrer-Szenarien. Programmieren Sie entsprechend defensiv.

Siehe auch

Navigation Navigation.currentEntry Event TaskPriorityChangeEvent XRInputSourcesChangeEvent