NavigationTransition.committed — Eigenschaft · JavaScript-Referenz

Signatur

NavigationTransition.committed

Beschreibung

Die schreibgeschützte Eigenschaft committed der Schnittstelle NavigationTransition liefert ein Promise<void>. Es wird genau dann erfüllt, wenn die laufende, per NavigateEvent.intercept() abgefangene Navigation festgeschrieben (committed) ist. Das heißt: navigation.currentEntry zeigt auf den neuen Eintrag und der Browser zeigt die neue URL an.

Das ist besonders wichtig, wenn Sie in intercept() einen precommitHandler verwenden. Dieser läuft vor dem Festschreiben, etwa um Daten vorzuladen oder die Navigation noch umzuleiten. Erst wenn alle precommitHandler-Promises erfüllt sind, wird die Navigation festgeschrieben und committed erfüllt. Danach laufen die normalen handler-Callbacks, und am Ende wird finished erfüllt. Die Reihenfolge ist also immer: committed zuerst, finished danach.

Scheitert die Navigation vor dem Festschreiben, wird das Promise mit einem Fehler zurückgewiesen. Das passiert zum Beispiel, wenn ein precommitHandler einen Fehler wirft, eine neue Navigation die alte ersetzt oder die Navigation über AbortSignal bzw. die Stopp-Schaltfläche abgebrochen wird. Typische Einsatzzwecke:

Ansicht, Titel oder Analyse-Ereignisse genau dann aktualisieren, wenn die neue URL wirklich gilt,
Code, der navigation.currentEntry ausliest, erst nach dem Festschreiben ausführen,
Ladeanzeigen trennen: eine für „URL gewechselt“ (committed) und eine für „Inhalt fertig“ (finished).

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Navigation festgeschrieben ist. Es wird zurückgewiesen (meist mit einer DOMException vom Typ AbortError), wenn die Navigation vorher scheitert oder abgebrochen wird.

Beispiele

Auf das Festschreiben einer abgefangenen Navigation warten

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

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

  // navigation.transition ist ab jetzt gesetzt
  navigation.transition?.committed
    .then(() => {
      console.log('Festgeschrieben:', navigation.currentEntry.url);
    })
    .catch((err) => console.warn('Nicht festgeschrieben:', err.name));
});

Festgeschrieben: https://example.com/artikel/42

precommitHandler: Daten laden, bevor die URL wechselt

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

  event.intercept({
    // läuft VOR dem Festschreiben, die alte URL bleibt noch sichtbar
    async precommitHandler() {
      const res = await fetch(`/api${url.pathname}`);
      if (!res.ok) throw new Error('Seite nicht gefunden');
      daten = await res.json();
    },
    // läuft NACH dem Festschreiben
    async handler() {
      document.title = daten.titel;
    }
  });

  const { committed, finished } = navigation.transition;
  committed.then(() => console.log('1. URL gewechselt'));
  finished.then(() => console.log('2. Inhalt fertig'));
  committed.catch((e) => console.log('Abgebrochen:', e.message));
});

1. URL gewechselt 2. Inhalt fertig

Getrennte Ladeanzeigen für URL-Wechsel und Rendern

const zeigeStatus = async () => {
  const transition = navigation.transition;
  if (!transition) return;

  document.body.dataset.status = 'lade';
  try {
    await transition.committed;
    document.body.dataset.status = 'rendere';
    await transition.finished;
    document.body.dataset.status = 'fertig';
  } catch {
    document.body.dataset.status = 'fehler';
  }
};

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  event.intercept({ handler: async () => { /* Inhalt laden */ } });
  zeigeStatus();
});

// Wichtig · Fallstricke

Kompatibilität: committed ist deutlich neuer als die übrige Navigation API und wurde zusammen mit precommitHandler eingeführt. Bisher gibt es sie nur in aktuellen Chromium-Browsern. Prüfen Sie vor der Nutzung, ob sie vorhanden ist, z. B. mit 'committed' in NavigationTransition.prototype, und greifen Sie sonst auf finished oder das Ereignis currententrychange zurück.
navigation.transition ist nur während einer abgefangenen Navigation gesetzt, sonst ist es null. Lesen Sie committed deshalb im navigate-Handler direkt nach intercept() aus, oder verwenden Sie optionales Verketten (?.).
Nicht verwechseln mit dem committed-Promise, das navigation.navigate(), reload(), back() usw. im Ergebnisobjekt zurückgeben. Dieses Promise wird mit dem neuen NavigationHistoryEntry erfüllt. NavigationTransition.committed liefert dagegen undefined.
Ohne precommitHandler wird die Navigation fast sofort festgeschrieben, und das Promise wird sehr früh erfüllt.
Hängen Sie immer ein .catch() an, wenn Sie nach einem Abbruch aufräumen müssen, z. B. eine Ladeanzeige zurücksetzen. Abbrüche durch eine neue Navigation kommen häufig vor.

Siehe auch

Navigation.transition NavigationActivation.from NavigationTransition.finished NavigationTransition.from NavigationTransition.to