Navigation.traverseTo() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.traverseTo(key, options)

Beschreibung

Die Methode traverseTo() der Navigation API springt gezielt zu einem bestimmten Eintrag der Sitzungshistorie, statt wie history.go(n) relativ um eine Anzahl von Schritten. Den Eintrag bestimmt man über dessen key, eine vom Browser vergebene, eindeutige Kennung eines Historien-Slots. Die Kennung bleibt gleich, auch wenn der Eintrag etwa per navigation.navigate(url, { history: "replace" }) ersetzt wird.

Das ist besonders in Single-Page-Anwendungen praktisch: Man merkt sich den key einer Startseite oder eines Listen-Zustands und kehrt später zuverlässig dorthin zurück, egal wie viele Einträge dazwischen entstanden sind. Mögliche Ziele liefert navigation.entries(), den aktuellen Eintrag navigation.currentEntry.

Wie navigate(), back() und forward() gibt die Methode ein Objekt mit zwei Promises zurück: committed erfüllt sich, sobald sich die sichtbare URL und currentEntry geändert haben, finished erst, wenn alle über event.intercept() registrierten Handler abgeschlossen sind. Beim Durchlaufen feuert auf dem navigation-Objekt ein navigate-Event mit navigationType === "traverse".

Parameter

Name	Typ	Default	Beschreibung
$key Pflicht	string		Der `key` des Ziel-Eintrags, z. B. aus `navigation.currentEntry.key` oder `navigation.entries()[i].key`.
$options	object	{}	Optionales Objekt mit der Eigenschaft `info` (`any`): beliebige Daten, die im `navigate`-Event als `event.info` ankommen. Sie werden nicht in der Historie gespeichert (anders als `state`).

Rückgabewert

Typ

{ committed: Promise<NavigationHistoryEntry>, finished: Promise<NavigationHistoryEntry> }

Beschreibung

Ein Objekt mit zwei Promises, die beide mit dem Ziel-NavigationHistoryEntry erfüllt werden: committed, sobald die Navigation festgeschrieben ist, und finished, sobald alle Intercept-Handler fertig sind. Scheitert die Navigation, werden beide mit einer DOMException abgelehnt, etwa InvalidStateError bei unbekanntem key oder AbortError bei Abbruch.

Beispiele

Zur gemerkten Startseite zurückspringen

// Beim Laden den Key des Einstiegs-Eintrags merken
const homeKey = navigation.currentEntry.key;

document.querySelector('#home-button').addEventListener('click', async () => {
  try {
    const { finished } = navigation.traverseTo(homeKey);
    const entry = await finished;
    console.log('Zurück auf:', entry.url);
  } catch (err) {
    console.error('Traversierung fehlgeschlagen:', err.name);
  }
});

Zurück auf: https://example.com/

Zum ersten Eintrag der Historie mit bestimmtem Pfad springen

const goToPath = async (pathname) => {
  const target = navigation.entries().find(
    (entry) => new URL(entry.url).pathname === pathname
  );

  if (!target) {
    // Kein passender Eintrag: normal vorwärts navigieren
    return navigation.navigate(pathname).finished;
  }
  if (target.key === navigation.currentEntry.key) return target;

  const { committed } = navigation.traverseTo(target.key, {
    info: { reason: 'breadcrumb' }
  });
  return committed;
};

goToPath('/produkte').then((entry) => console.log('Index:', entry.index));

Index: 1

Traversierung im navigate-Event erkennen und info auswerten

navigation.addEventListener('navigate', (event) => {
  if (event.navigationType !== 'traverse') return;
  if (!event.canIntercept) return;

  console.log('Traverse, Grund:', event.info?.reason ?? 'Browser-Button');

  event.intercept({
    handler: async () => {
      const url = new URL(event.destination.url);
      document.title = `Seite ${url.pathname}`;
    }
  });
});

const [first] = navigation.entries();
navigation.traverseTo(first.key, { info: { reason: 'reset' } });

Traverse, Grund: reset

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API ist in Chromium-Browsern seit Version 102 verfügbar und erst in neueren Versionen von Firefox und Safari. Deshalb vorher mit if ('navigation' in window) prüfen und bei Bedarf auf history.go() ausweichen.
Unbekannter Key: Existiert kein Eintrag mit diesem key in navigation.entries() (etwa weil der Eintrag durch eine neue Navigation abgeschnitten wurde), werden beide Promises mit InvalidStateError abgelehnt. Es wird keine Ausnahme synchron geworfen.
Nur gleicher Ursprung: entries() enthält nur Einträge desselben Dokument-Ursprungs. Einträge anderer Seiten sind nicht erreichbar.
Aktueller Eintrag: Ist key der Key des aktuellen Eintrags, passiert nichts und die Promises erfüllen sich sofort.
Nicht abfangbar über Dokumentgrenzen: Führt die Traversierung in ein anderes Dokument, ist event.canIntercept false. Außerdem lassen sich traverse-Navigationen nicht per preventDefault() abbrechen (Ausnahme: gleiches Dokument und Auslösung durch Benutzeraktivierung in neueren Chrome-Versionen).
key und id nicht verwechseln: id ändert sich beim Ersetzen eines Eintrags, key bleibt gleich. Für traverseTo() immer key verwenden.
Unbehandelte Ablehnungen von committed/finished erscheinen als „Uncaught (in promise)“. Deshalb mindestens finished mit await/catch behandeln.

Siehe auch

Navigation Navigation.navigate() Navigation.back() Navigation.forward() Navigation.entries() Navigation.currentEntry NavigationHistoryEntry History.go()