NavigationDestination — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigationDestination

Beschreibung

NavigationDestination gehört zur Navigation API und beschreibt, wohin eine Navigation führt, bevor sie abgeschlossen ist. Du erzeugst keine Instanz selbst: Der Browser übergibt sie über die Eigenschaft destination des NavigateEvent, das beim Ereignis navigate auf window.navigation ausgelöst wird.

Typisch ist der Einsatz beim clientseitigen Routing in Single-Page-Apps: Im navigate-Handler liest du destination.url, suchst die passende Route und fängst die Navigation mit event.intercept() ab, um den Inhalt selbst zu rendern, statt die Seite neu zu laden.

Das Interface hat diese nur lesbaren Eigenschaften und eine Methode:

url – die Ziel-URL als absoluter String.
key – der key des Ziel-NavigationHistoryEntry bei "traverse"-Navigationen, sonst ein leerer String.
id – die id des Ziel-Eintrags bei "traverse", sonst ein leerer String.
index – der Index des Ziel-Eintrags in navigation.entries() bei "traverse", sonst -1.
sameDocument – true, wenn im selben Dokument navigiert wird (z. B. über einen Fragment-Link oder history.pushState()).
getState() – gibt eine Kopie des Zustands zurück, der mit dem Ziel verknüpft ist (z. B. state aus navigation.navigate(url, { state })).

Rückgabewert

Typ

NavigationDestination

Beschreibung

Wird nicht selbst erzeugt, sondern über NavigateEvent.destination geliefert. Ein Konstruktor ist nicht verfügbar.

Beispiele

Einfacher SPA-Router mit destination.url

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

navigation.addEventListener('navigate', (event) => {
  // Nur Navigationen innerhalb der eigenen Anwendung abfangen
  if (!event.canIntercept || event.hashChange || event.downloadRequest !== null) return;

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

  event.intercept({
    async handler() {
      document.querySelector('main').textContent = '';
      document.querySelector('main').insertAdjacentHTML('beforeend', render());
    }
  });
});

Zustand mit getState() auslesen

navigation.addEventListener('navigate', (event) => {
  const state = event.destination.getState();
  console.log('Ziel:', event.destination.url);
  console.log('Zustand:', state);
});

// Navigation mit angehängtem Zustand auslösen
navigation.navigate('/produkte?id=42', { state: { quelle: 'suche', seite: 3 } });

Ziel: https://example.com/produkte?id=42 Zustand: { quelle: 'suche', seite: 3 }

Vor- und Zurück-Navigation erkennen

navigation.addEventListener('navigate', (event) => {
  const { destination, navigationType } = event;

  if (navigationType === 'traverse') {
    const richtung = destination.index < navigation.currentEntry.index ? 'zurück' : 'vor';
    console.log(`Traverse ${richtung} zu Index ${destination.index}, key=${destination.key}`);
  } else {
    // Bei push/replace/reload gibt es noch keinen Ziel-Eintrag
    console.log(destination.index, JSON.stringify(destination.key));
  }
  console.log('Gleiches Dokument?', destination.sameDocument);
});

Traverse zurück zu Index 1, key=3f2a… Gleiches Dokument? true

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser seit Version 102; Firefox und Safari haben die Navigation API erst sehr spät eingeführt. Prüfe vorher mit 'navigation' in window und behalte history/popstate als Rückfallebene bei.
key, id und index sind nur bei navigationType === "traverse" gefüllt. Bei "push", "replace" und "reload" sind sie "" bzw. -1, weil der Ziel-Eintrag noch nicht existiert.
getState() liefert eine strukturierte Kopie (Structured Clone). Wenn du das zurückgegebene Objekt änderst, ändert sich der gespeicherte Zustand nicht. Funktionen und DOM-Knoten lassen sich nicht als Zustand speichern.
url ist ein String und kann auf eine fremde Origin zeigen. Parse ihn mit new URL() und prüfe event.canIntercept, bevor du abfängst. Fremde URLs lassen sich nicht abfangen.
Die Instanz gilt nur für das jeweilige NavigateEvent. Nach der Navigation findest du die Daten über navigation.currentEntry.

Siehe auch

Navigation Navigation.prototype.navigate() History NavigationActivation NavigationTransition