NavigationTransition.finished — Eigenschaft · JavaScript-Referenz

Signatur

NavigationTransition.finished

Beschreibung

Die schreibgeschützte Eigenschaft finished eines NavigationTransition-Objekts gibt ein Promise zurück, das den Abschluss der gerade laufenden Navigation meldet. Es wird erfüllt, sobald das Ereignis navigatesuccess am navigation-Objekt ausgelöst wird. Es wird abgelehnt, wenn navigateerror ausgelöst wird, also wenn ein an event.intercept() übergebener Handler ein abgelehntes Promise liefert, die Navigation per AbortSignal abgebrochen oder durch eine neue Navigation ersetzt wird.

An das aktuelle Übergangsobjekt kommt man über navigation.transition. Diese Eigenschaft ist nur gesetzt, solange eine abgefangene Navigation läuft, sonst hat sie den Wert null. Typische Anwendungen sind Ladeindikatoren, Fokus- und Scroll-Steuerung sowie Analyse-Code, der erst laufen soll, wenn die neue Ansicht in einer Single-Page-App fertig gerendert ist.

Wichtig ist der Unterschied zu den Promises, die navigation.navigate() zurückgibt: committed wird erfüllt, sobald URL und Verlaufseintrag geändert sind, finished erst dann, wenn alle Intercept-Handler fertig sind. NavigationTransition.finished entspricht inhaltlich dem finished-Promise aus navigation.navigate(), ist aber auch bei Navigationen erreichbar, die man nicht selbst gestartet hat, zum Beispiel bei Klicks auf Links oder dem Zurück-Button.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Navigation erfolgreich abgeschlossen ist. Es wird mit einem Fehler abgelehnt (z. B. einer DOMException vom Typ AbortError), wenn die Navigation fehlschlägt oder abgebrochen wird.

Beispiele

Ladeindikator bis zum Navigationsende anzeigen

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

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  const url = new URL(event.destination.url);

  event.intercept({
    async handler() {
      const res = await fetch(`/partials${url.pathname}`);
      document.querySelector('main').innerHTML = await res.text();
    }
  });

  // navigation.transition ist ab jetzt gesetzt
  spinner.hidden = false;
  navigation.transition?.finished
    .catch(() => {}) // Abbruch oder Fehler abfangen
    .finally(() => { spinner.hidden = true; });
});

Fehlgeschlagene oder abgebrochene Navigation erkennen

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  event.intercept({
    handler: () => new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Server nicht erreichbar')), 500))
  });
});

navigation.navigate('/profil');

try {
  await navigation.transition.finished;
  console.log('Navigation abgeschlossen');
} catch (err) {
  console.warn('Navigation fehlgeschlagen:', err.message);
}

Navigation fehlgeschlagen: Server nicht erreichbar

Fokus nach Abschluss setzen und Übergangsart protokollieren

const logTransition = async () => {
  const transition = navigation.transition;
  if (!transition) {
    console.log('Keine laufende Navigation');
    return;
  }
  const { navigationType, from } = transition;
  try {
    await transition.finished;
    console.log(`${navigationType} von ${from.url} abgeschlossen`);
    document.querySelector('h1')?.focus();
  } catch {
    console.log('Übergang wurde abgebrochen');
  }
};

navigation.addEventListener('navigate', (e) => {
  if (e.canIntercept) e.intercept({ handler: async () => {} });
  queueMicrotask(logTransition);
});

push von https://example.com/ abgeschlossen

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102 und in Firefox seit Version 147. Safari unterstützt sie erst in neueren Versionen (ab 26.2), daher ist sie erst seit Anfang 2026 Baseline („neu verfügbar“). Vor der Nutzung mit if ('navigation' in window) prüfen und für ältere Browser eine Ausweichlösung mit der History API vorsehen.
Unbehandelte Ablehnungen: Wird eine Navigation abgebrochen (z. B. weil eine neue Navigation beginnt), wird finished abgelehnt. Ohne .catch() erscheint dann ein unhandledrejection-Fehler in der Konsole.
navigation.transition kann null sein: Es gibt nur dann ein Übergangsobjekt, wenn die Navigation mit event.intercept() abgefangen wurde und noch läuft. Deshalb optionale Verkettung (?.) verwenden oder vorher prüfen.
Die Referenz auf navigation.transition vor dem ersten await in einer Variablen speichern, weil die Eigenschaft nach dem Ende der Navigation auf null zurückgesetzt wird.
Nur im Hauptdokument des Fensters verfügbar, nicht in Workern.

Siehe auch

Navigation.transition Navigation.navigate() NavigationTransition.committed NavigationTransition.from NavigationTransition.to