NavigationTransition — Schnittstelle · JavaScript-Referenz

Signatur

interface NavigationTransition

Beschreibung

NavigationTransition gehört zur Navigation API. Ein Objekt dieser Art beschreibt eine Navigation, die gerade läuft, also von einem navigate-Handler per event.intercept() abgefangen wurde und deren Handler-Promises noch nicht erfüllt sind. Das aktuelle Objekt liefert navigation.transition. Läuft gerade keine Navigation, ist der Wert null.

Das Interface stellt folgende schreibgeschützte Eigenschaften bereit:

navigationType: Art der Navigation, also "push", "replace", "reload" oder "traverse".
from: der NavigationHistoryEntry, von dem aus navigiert wird.
finished: ein Promise<undefined>. Es wird erfüllt, sobald navigatesuccess ausgelöst wird, und abgelehnt, wenn die Navigation fehlschlägt oder abgebrochen wird (navigateerror).
committed (neuer): ein Promise, das erfüllt wird, sobald sich die URL geändert hat und der neue Eintrag übernommen (committed) wurde.

Typische Einsatzfälle in Single-Page-Anwendungen: Ladeanzeigen ein- und ausblenden, auf das Ende einer Navigation warten (z. B. in Tests oder vor dem Scroll-Wiederherstellen) oder Übergangsanimationen je nach Navigationsrichtung und Ausgangsseite wählen.

Einen Konstruktor gibt es nicht. Instanzen erzeugt ausschließlich der Browser.

Rückgabewert

Typ

NavigationTransition | null

Beschreibung

navigation.transition liefert das Objekt der laufenden Navigation oder null, wenn gerade keine abgefangene Navigation läuft.

Beispiele

Laufende Navigation abfragen und Eigenschaften lesen

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  event.intercept({
    handler: async () => {
      // Während der Handler läuft, gibt es eine Transition
      const t = navigation.transition;
      console.log(t.navigationType);     // z. B. "push"
      console.log(t.from.url);           // URL der Ausgangsseite
      await new Promise((r) => setTimeout(r, 300));
    }
  });
});

navigation.navigate('/produkte');

push https://example.com/

Ladeanzeige über transition.finished steuern

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();
    }
  });

  // Transition ist erst nach intercept() gesetzt
  const transition = navigation.transition;
  spinner.hidden = false;
  transition?.finished
    .catch((err) => console.warn('Navigation fehlgeschlagen:', err.name))
    .finally(() => { spinner.hidden = true; });
});

Vor weiterer Logik auf das Ende einer Navigation warten

const waitForNavigation = async () => {
  const t = navigation.transition;
  if (!t) return 'keine Navigation aktiv';
  try {
    await t.finished;
    return `fertig (${t.navigationType})`;
  } catch (err) {
    return `abgebrochen: ${err.name}`;
  }
};

navigation.navigate('/konto');
console.log(await waitForNavigation());

fertig (push)

Animationsrichtung anhand von from und navigationType wählen

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  event.intercept({
    handler: async () => {
      const { navigationType, from } = navigation.transition;
      const back = navigationType === 'traverse' &&
        event.destination.index < from.index;
      document.documentElement.dataset.richtung = back ? 'zurueck' : 'vor';
      // ... Inhalt rendern
    }
  });
});

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102. Firefox und Safari unterstützen sie erst in neueren Versionen. Prüfe die Unterstützung vorher mit if ('navigation' in window) und halte für ältere Browser einen Weg über die History API bereit. Die Eigenschaft committed ist deutlich neuer und noch nicht überall verfügbar.
navigation.transition ist nur gesetzt, wenn die Navigation per event.intercept() abgefangen wurde. Bei normalen Navigationen, die ein neues Dokument laden, und nach dem Abschluss ist der Wert null. Prüfe ihn deshalb mit ?. oder einer if-Abfrage.
Startet eine neue Navigation, während eine andere noch läuft, wird die alte abgebrochen. Ihr finished-Promise wird dann mit einer AbortError-DOMException abgelehnt. Behandle Ablehnungen daher immer mit try/catch oder .catch().
Zwischen finished und den Ereignissen gilt: Wird finished erfüllt, feuert auch navigatesuccess. Wird es abgelehnt, feuert navigateerror. Für globales Logging eignen sich die Ereignisse, für eine einzelne Navigation das Promise.
Die Navigation API gibt es nur im Fenster-Kontext, nicht in Web Workers oder Node.js.

Siehe auch

Navigation Navigation.transition NavigationActivation NavigationDestination ViewTransition