Navigation.forward() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.forward(options)

Beschreibung

navigation.forward() ist das moderne Gegenstück zu history.forward(). Die Methode geht in der Liste der Navigationseinträge (navigation.entries()) einen Schritt nach vorn. Voraussetzung: Es gibt überhaupt einen nächsten Eintrag, navigation.canGoForward muss also true sein.

Der große Vorteil gegenüber der alten History-API ist der Rückgabewert. Du bekommst ein NavigationResult-Objekt mit zwei Promises: committed erfüllt sich, sobald sich die sichtbare URL geändert hat und der neue Eintrag aktiv ist. finished erfüllt sich erst, wenn alle Handler abgeschlossen sind, die im navigate-Event über intercept() registriert wurden. Deshalb eignet sich die Methode gut für Single-Page-Anwendungen: Du kannst auf das Ende der Navigation warten und Fehler sauber mit try/catch abfangen.

Die Methode löst ein navigate-Event vom Typ "traverse" aus. Über options.info gibst du beliebige Daten mit, die im Event als event.info ankommen. Diese Daten werden nicht im Eintrag gespeichert, sondern gelten nur für diese eine Navigation.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Objekt mit Einstellungen für die Navigation.
$options.info	any	undefined	Beliebige Daten, die im ausgelösten `navigate`-Event als `event.info` ankommen, z. B. die Richtung für eine Animation.

Rückgabewert

Typ

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

Beschreibung

Ein NavigationResult-Objekt. committed erfüllt sich, sobald die URL gewechselt hat. finished erfüllt sich, wenn alle intercept()-Handler abgeschlossen sind. Beide Promises liefern den neuen NavigationHistoryEntry oder werden bei Fehler oder Abbruch mit einer DOMException zurückgewiesen.

Beispiele

Vorwärts-Button mit Prüfung über canGoForward

const forwardBtn = document.querySelector('#forward');

const updateButton = () => {
  // Button nur aktivieren, wenn es einen nächsten Eintrag gibt
  forwardBtn.disabled = !navigation.canGoForward;
};

forwardBtn.addEventListener('click', async () => {
  if (!navigation.canGoForward) return;
  try {
    const entry = await navigation.forward().finished;
    console.log('Jetzt auf:', entry.url);
  } catch (err) {
    console.error('Navigation fehlgeschlagen:', err.name);
  }
});

navigation.addEventListener('currententrychange', updateButton);
updateButton();

Jetzt auf: https://example.com/produkte

Info-Daten für eine Übergangsanimation mitgeben

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

  event.intercept({
    async handler() {
      const richtung = event.info?.richtung ?? 'keine';
      console.log('Animation:', richtung);
      document.body.dataset.transition = richtung;
      await renderRoute(new URL(event.destination.url).pathname);
    }
  });
});

const renderRoute = async (path) => {
  document.querySelector('main').textContent = `Seite: ${path}`;
};

// Später, z. B. per Wisch-Geste:
navigation.forward({ info: { richtung: 'links' } });

Animation: links

committed und finished getrennt auswerten

const goForward = async () => {
  if (!navigation.canGoForward) {
    console.log('Kein Vorwärts-Eintrag vorhanden');
    return;
  }
  const { committed, finished } = navigation.forward();

  const entry = await committed;
  console.log('URL gewechselt, Index:', entry.index);

  await finished;
  console.log('Seite fertig gerendert');
};

goForward();

URL gewechselt, Index: 3 Seite fertig gerendert

// Wichtig · Fallstricke

Kein nächster Eintrag: Ist navigation.canGoForward false, werden beide Promises mit einer DOMException vom Typ InvalidStateError zurückgewiesen. Prüfe das also vorher, oder fange den Fehler ab. Eine unbehandelte Zurückweisung erzeugt sonst eine Konsolenwarnung.
Abbruch: Wird die Navigation durch eine neue Navigation unterbrochen oder ruft ein Handler event.preventDefault() auf, weisen die Promises mit AbortError zurück.
Nur eigener Ursprung: navigation.entries() enthält nur Einträge desselben Ursprungs im aktuellen Dokument-Kontext. Einträge fremder Ursprünge sind nicht sichtbar. canGoForward kann deshalb false sein, obwohl der Vorwärts-Button des Browsers aktiv ist.
Nicht abfangbar: Beim Wechsel zwischen verschiedenen Dokumenten ist event.canIntercept false. intercept() funktioniert dann nicht.
Browser-Kompatibilität: Die Navigation API gibt es in Chromium-basierten Browsern ab Version 102. In Firefox (ab 147) und Safari (ab 26.2) kam sie erst spät dazu. Für ältere Browser mit 'navigation' in window prüfen und auf history.forward() ausweichen.

Siehe auch

Navigation.back() Navigation.navigate() History.forward() Navigation Navigation.reload()