Window.navigation — Eigenschaft · JavaScript-Referenz

Signatur

get Window.navigation

Beschreibung

window.navigation liefert das Navigation-Objekt, das zum aktuellen Browsing-Kontext gehört. Es ist der Einstiegspunkt in die Navigation API, den modernen Nachfolger der History API (history.pushState(), popstate). Darüber kannst du Navigationen starten, abfangen und überwachen und auf den Sitzungsverlauf der eigenen Herkunft (Origin) zugreifen.

Besonders nützlich ist die API für Single-Page-Anwendungen. Ein zentraler navigate-Event-Listener fängt alle Navigationen ab: Linkklicks, Formularversand, Zurück/Vor-Tasten und programmatische Aufrufe. Mit event.intercept() verwandelst du sie in eine Navigation innerhalb des Dokuments. Klick-Handler an jedem einzelnen Link und das fehleranfällige Zusammenspiel von pushState und popstate fallen damit weg.

Wichtige Bestandteile des zurückgegebenen Objekts:

navigation.currentEntry: aktueller Verlaufseintrag (NavigationHistoryEntry) mit url, key, id und getState().
navigation.entries(): alle Einträge des Verlaufs, die zur gleichen Herkunft gehören.
navigation.navigate(), reload(), back(), forward(), traverseTo(key): programmatische Navigation. Jede dieser Methoden gibt ein Objekt mit den Promises committed und finished zurück.
navigation.updateCurrentEntry({ state }): ändert den Zustand des aktuellen Eintrags, ohne zu navigieren.
navigation.canGoBack / canGoForward, navigation.transition sowie die Events navigate, navigatesuccess, navigateerror und currententrychange.

Die Eigenschaft ist schreibgeschützt. Sie gibt für ein Fenster immer dasselbe Objekt zurück und hat keine Parameter.

Rückgabewert

Typ

Navigation

Beschreibung

Das Navigation-Objekt des aktuellen Fensters. In Browsern ohne Navigation API gibt es die Eigenschaft nicht, dann ist window.navigation undefined.

Beispiele

Unterstützung prüfen und aktuellen Eintrag auslesen

if ('navigation' in window) {
  const { currentEntry } = window.navigation;
  console.log('URL:', currentEntry.url);
  console.log('Index im Verlauf:', currentEntry.index);
  console.log('Einträge gleicher Herkunft:', navigation.entries().length);
  console.log('Zurück möglich?', navigation.canGoBack);
} else {
  console.log('Navigation API nicht verfügbar – Rückfall auf History API');
}

URL: https://example.com/produkte Index im Verlauf: 2 Einträge gleicher Herkunft: 3 Zurück möglich? true

SPA-Routing: Navigationen zentral abfangen

const routes = {
  '/': () => '<h1>Startseite</h1>',
  '/kontakt': () => '<h1>Kontakt</h1>',
};

navigation.addEventListener('navigate', (event) => {
  // Downloads, fremde Herkunft usw. nicht abfangen
  if (!event.canIntercept || event.hashChange || event.downloadRequest !== null) return;

  const url = new URL(event.destination.url);
  const render = routes[url.pathname];
  if (!render) return; // normale Navigation zulassen

  event.intercept({
    async handler() {
      // z. B. Daten laden – event.signal bricht bei neuer Navigation ab
      await new Promise((r) => setTimeout(r, 100));
      document.querySelector('main').innerHTML = render();
    },
  });
});

navigation.addEventListener('navigatesuccess', () => {
  console.log('Navigiert zu', navigation.currentEntry.url);
});

Navigiert zu https://example.com/kontakt

Programmatisch navigieren mit Zustand

const oeffneProdukt = async (id) => {
  const { committed, finished } = navigation.navigate(`/produkt/${id}`, {
    state: { produktId: id, scrollPos: 0 },
    history: 'push', // oder 'replace'
  });
  await committed; // URL ist bereits geändert
  await finished;  // Handler aus intercept() ist fertig
  console.log('Zustand:', navigation.currentEntry.getState());
};

oeffneProdukt(42);

// Zustand ändern, ohne zu navigieren
navigation.updateCurrentEntry({ state: { produktId: 42, scrollPos: 350 } });

Zustand: { produktId: 42, scrollPos: 0 }

Zu einem bestimmten Verlaufseintrag springen

// Key des Startseiten-Eintrags merken
const startKey = navigation.currentEntry.key;

// ... später, nach mehreren Navigationen:
const zurueckZumStart = async () => {
  try {
    await navigation.traverseTo(startKey).finished;
    console.log('Wieder auf', navigation.currentEntry.url);
  } catch (err) {
    console.error('Sprung fehlgeschlagen:', err.name);
  }
};

Wieder auf https://example.com/

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser (Chrome, Edge, Opera) unterstützen die Navigation API seit Version 102. Firefox und Safari haben sie erst deutlich später und nur in sehr aktuellen Versionen eingeführt. Prüfe die Unterstützung deshalb immer mit 'navigation' in window und halte für ältere Browser einen Rückfall auf die History API bereit.

navigation.entries() enthält nur Einträge derselben Herkunft im aktuellen Frame. Einträge anderer Websites im Verlauf bleiben unsichtbar.
Nicht jede Navigation lässt sich abfangen. Prüfe vorher event.canIntercept, denn Navigationen zu einer fremden Herkunft lassen sich nicht in dokumentinterne Navigationen umwandeln. Zurück/Vor-Navigationen kannst du mit event.preventDefault() nur eingeschränkt abbrechen, meist nur, wenn der Nutzer vorher mit der Seite interagiert hat (event.cancelable prüfen).
Den Zustand mit getState() speichert der Browser per Structured Clone. Funktionen und DOM-Knoten sind darin also nicht erlaubt. Das Ergebnis ist außerdem jedes Mal eine Kopie: Änderungen daran werden erst mit updateCurrentEntry() gespeichert.
Die Promises committed und finished werden mit einer AbortError-DOMException zurückgewiesen, wenn eine neue Navigation die laufende abbricht. Behandle diese Zurückweisungen, damit keine unbehandelten Fehler entstehen.
Die Navigation API existiert nur im Fensterkontext. In Web Workern und in Node.js gibt es sie nicht.

Siehe auch

Navigation Navigation.prototype.navigate() Window.history History.prototype.pushState() Window.location