Navigation.transition — Eigenschaft · JavaScript-Referenz

Signatur

get Navigation.transition

Beschreibung

Die schreibgeschützte Eigenschaft transition der Navigation-Schnittstelle (erreichbar über window.navigation) liefert ein NavigationTransition-Objekt, das eine gerade laufende Navigation beschreibt. Darüber kannst du den Zustand einer Navigation verfolgen, die in einem navigate-Handler per event.intercept() abgefangen wurde. Das ist typisch für Single-Page-Anwendungen.

Das Objekt stellt diese Informationen bereit:

navigationType: Art der Navigation ("push", "replace", "reload" oder "traverse").
from: der NavigationHistoryEntry, von dem aus navigiert wird.
finished: ein Promise, das erfüllt wird, wenn alle an intercept() übergebenen Handler fertig sind. Wird die Navigation abgebrochen oder schlägt ein Handler fehl, wird es zurückgewiesen.
committed (neuer): ein Promise, das erfüllt wird, sobald die neue URL übernommen wurde.

Außerhalb einer abgefangenen Navigation ist der Wert null. Das gilt auch für normale Navigationen, bei denen ein neues Dokument geladen wird, und für Navigationen ohne intercept(). Mit dieser Eigenschaft lassen sich zum Beispiel Ladeanzeigen steuern, Aktionen auf das Ende einer Navigation verschieben oder Übergangsanimationen passend zur Navigationsrichtung auswählen.

Rückgabewert

Typ

NavigationTransition | null

Beschreibung

Ein NavigationTransition-Objekt für die laufende abgefangene Navigation, sonst null.

Beispiele

Ladeanzeige während einer SPA-Navigation

const spinner = document.querySelector('#spinner');

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept || event.hashChange) return;
  event.intercept({
    handler: async () => {
      const res = await fetch(new URL(event.destination.url).pathname + '?partial=1');
      document.querySelector('main').innerHTML = await res.text();
    }
  });

  // Ab hier ist navigation.transition gesetzt
  spinner.hidden = false;
  navigation.transition?.finished
    .catch(() => console.warn('Navigation abgebrochen oder fehlgeschlagen'))
    .finally(() => { spinner.hidden = true; });
});

Auf das Ende einer laufenden Navigation warten

const waitForNavigation = async () => {
  const transition = navigation.transition;
  if (!transition) {
    console.log('Keine Navigation aktiv');
    return;
  }
  console.log(`Läuft: ${transition.navigationType} von ${transition.from.url}`);
  try {
    await transition.finished;
    console.log('Fertig, jetzt bei', navigation.currentEntry.url);
  } catch (err) {
    console.log('Abgebrochen:', err.name);
  }
};

navigation.navigate('/produkte');
waitForNavigation();

Läuft: push von https://example.com/ Fertig, jetzt bei https://example.com/produkte

Animation nach Navigationsrichtung wählen

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  event.intercept({ handler: () => renderRoute(event.destination.url) });

  const { navigationType, from } = navigation.transition;
  const back = navigationType === 'traverse' &&
    event.destination.index < from.index;
  document.documentElement.dataset.direction = back ? 'back' : 'forward';
});

const renderRoute = async (url) => {
  document.querySelector('h1').textContent = new URL(url).pathname;
};

// Wichtig · Fallstricke

Nur bei abgefangenen Navigationen: transition ist nur gesetzt, wenn im navigate-Handler event.intercept() aufgerufen wurde. Vorher, also auch am Anfang des Handlers, ist der Wert noch null. Prüfe den Wert deshalb immer mit ?. oder einer if-Abfrage.
Die Eigenschaft ist nicht live. Speicherst du das Objekt und startet danach eine neue Navigation, beschreibt es weiter die alte Navigation. Deren finished-Promise wird dann mit einem AbortError zurückgewiesen.
Das finished-Promise ist intern als behandelt markiert. Eine Zurückweisung erzeugt also keine unhandled rejection. Fehler solltest du trotzdem gezielt mit catch auswerten oder das Event navigateerror nutzen.
Kompatibilität: Die Navigation API gibt es in Chromium-Browsern ab Version 102. Firefox und Safari unterstützen sie erst in sehr neuen Versionen. Prüfe die Unterstützung mit 'navigation' in window und sieh eine Ausweichlösung über die History API vor. NavigationTransition.committed ist neuer und wird noch nicht überall unterstützt.

Siehe auch

Navigation Navigation.activation Navigation.canGoBack Navigation.currentEntry Navigation.canGoForward