NavigationHistoryEntry: dispose — Ereignis · JavaScript-Referenz

Signatur

navigationHistoryEntry.addEventListener("dispose", handler)

Beschreibung

Das Ereignis dispose gehört zum Interface NavigationHistoryEntry der Navigation API. Es wird genau einmal ausgelöst, sobald der Eintrag nicht mehr Teil von navigation.entries() ist. Danach ist der Eintrag „tot“: Über ihn kann nicht mehr navigiert werden, und sein Zustand ist nicht mehr erreichbar.

Typische Auslöser sind:

Eine neue Navigation mit push, nachdem man im Verlauf zurückgegangen ist. Alle „Vorwärts“-Einträge werden dabei verworfen.
Eine Navigation mit replace. Der aktuelle Eintrag wird durch einen neuen ersetzt.
Der Browser kürzt den Verlauf, zum Beispiel wenn eine Obergrenze erreicht ist.

Nützlich ist das Ereignis zum Aufräumen. Wer Daten an einen Eintrag bindet (etwa in einer Map nach entry.key oder entry.id, im Cache oder in IndexedDB), kann sie im Handler wieder freigeben. So wächst der Speicher in Single-Page-Anwendungen nicht unbegrenzt. Den Handler registriert man mit addEventListener("dispose", ...) oder über die Eigenschaft ondispose.

Das Ereignis ist ein einfaches Event ohne eigene Zusatzdaten. Es steigt nicht auf (kein Bubbling) und lässt sich nicht abbrechen. Welcher Eintrag betroffen ist, verrät event.target.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"dispose"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie erhält ein einfaches `Event`. `event.target` ist der entfernte `NavigationHistoryEntry`.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once` oder `signal`. Da das Ereignis ohnehin nur einmal pro Eintrag kommt, ist `signal` vor allem zum vorzeitigen Abmelden nützlich.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt.

Beispiele

Einträge mit addEventListener überwachen

// Für jeden neuen aktuellen Eintrag einen dispose-Handler registrieren
const watch = (entry) => {
  entry.addEventListener("dispose", (event) => {
    console.log(`Eintrag entfernt: ${event.target.url}`);
  });
};

watch(navigation.currentEntry);
navigation.addEventListener("currententrychange", () => {
  watch(navigation.currentEntry);
});

// Test: replace verwirft den aktuellen Eintrag
await navigation.navigate("#neu", { history: "replace" }).committed;

Eintrag entfernt: https://example.com/seite

Pro Eintrag gespeicherte Daten freigeben (ondispose)

// Scroll-Position und Formulardaten je Verlaufseintrag cachen
const entryCache = new Map();

const remember = (entry, data) => {
  entryCache.set(entry.key, data);
  entry.ondispose = () => {
    entryCache.delete(entry.key);
    console.log(`Cache bereinigt, verbleibend: ${entryCache.size}`);
  };
};

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

Cache bereinigt, verbleibend: 0

Vorwärts-Einträge verwerfen und Anmeldung per AbortController

const controller = new AbortController();

for (const entry of navigation.entries()) {
  entry.addEventListener(
    "dispose",
    () => console.log(`Verworfen (Index ${entry.index}):`, entry.url),
    { signal: controller.signal }
  );
}

// Zurückgehen und dann neu pushen -> Vorwärts-Einträge werden verworfen
if (navigation.canGoBack) {
  await navigation.back().finished;
  await navigation.navigate("/andere-seite").committed;
}

// Alle verbliebenen Listener sauber abmelden
controller.abort();

Verworfen (Index -1): https://example.com/vorher-vorwaerts

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API gibt es in Chromium-Browsern seit Version 102, in Firefox seit 147 und in Safari seit 26.2. Seit Anfang 2026 ist sie damit Baseline. Für ältere Browser trotzdem mit if (\"navigation\" in window) prüfen und notfalls auf die History API ausweichen.
Es werden nur Einträge desselben Ursprungs im aktuellen Frame berücksichtigt. Einträge anderer Ursprünge tauchen in navigation.entries() gar nicht auf.
Nach dispose ist entry.index gleich -1. navigation.traverseTo(entry.key) schlägt dann fehl.
Beim Entladen oder Schließen der Seite gibt es kein dispose. Wichtige Daten also nicht nur hier speichern oder aufräumen, sondern auch pagehide nutzen.
Bei reload() bleibt der Eintrag erhalten. Es gibt also kein dispose.
Handler, die an einen Eintrag gebunden sind, halten per Closure Referenzen fest. Nach dem Ereignis den Handler entfernen oder { once: true } verwenden, damit keine Speicherlecks entstehen.

Siehe auch

Navigation Navigation.entries() Navigation: currententrychange Navigation.navigate() MediaStream: addtrack