NavigationPrecommitController.addHandler() — Methode · JavaScript-Referenz

Signatur

NavigationPrecommitController.prototype.addHandler(handler)

Beschreibung

Mit addHandler() registrieren Sie aus dem Precommit-Code einer abgefangenen Navigation heraus eine Callback-Funktion. Sie wirkt so, als hätten Sie sie beim Aufruf von NavigateEvent.intercept() als Option handler übergeben. Die Funktion läuft, nachdem die Navigation committet wurde, also nachdem die URL aktualisiert und der Verlaufseintrag angelegt ist.

Nützlich ist das, wenn Sie erst im precommitHandler entscheiden können, welche Darstellungslogik nötig ist. Ein Beispiel: Sie laden vor dem Commit Daten oder prüfen Berechtigungen und hängen je nach Ergebnis einen passenden Render-Handler an. Oder Sie leiten mit controller.redirect() um und verzichten ganz auf einen Handler.

Das NavigationPrecommitController-Objekt erhalten Sie nur als Argument des precommitHandler, den Sie an event.intercept({ precommitHandler }) übergeben. Außerhalb dieses Callbacks gibt es keinen Zugriff darauf. Sie können mehrere Handler hinzufügen. Sie laufen dann zusammen mit den Handlern aus intercept(), und die Navigation gilt erst als abgeschlossen, wenn alle zurückgegebenen Promises erfüllt sind.

Parameter

Name	Typ	Default	Beschreibung
$handler Pflicht	() => Promise<void> \| void		Callback, die nach dem Commit der Navigation aufgerufen wird. Gibt sie ein Promise zurück, wartet die Navigation, bis es erfüllt ist. Wird es abgelehnt, schlägt die Navigation fehl (`navigateerror`).

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

Render-Handler nach dem Laden der Daten hinzufügen

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

  event.intercept({
    async precommitHandler(controller) {
      // Daten laden, bevor sich die URL ändert
      const res = await fetch(`/api${url.pathname}`, { signal: event.signal });
      const artikel = await res.json();

      // Darstellung erst nach dem Commit ausführen
      controller.addHandler(async () => {
        document.querySelector('main').textContent = artikel.titel;
      });
    }
  });
});

Je nach Ergebnis umleiten oder einen Handler anhängen

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

  event.intercept({
    async precommitHandler(controller) {
      const res = await fetch('/api/session', { signal: event.signal });
      const { angemeldet } = await res.json();

      if (!angemeldet) {
        // Vor dem Commit auf die Login-Seite umleiten
        controller.redirect('/login');
        return;
      }

      controller.addHandler(() => {
        document.title = 'Mein Konto';
        console.log('Kontoseite gerendert');
      });
    }
  });
});

Kontoseite gerendert

Feature-Erkennung mit Fallback

navigation.addEventListener('navigate', (event) => {
  if (!event.canIntercept) return;
  const render = () => console.log('Rendern für', event.destination.url);

  if ('NavigationPrecommitController' in window) {
    event.intercept({
      precommitHandler(controller) {
        controller.addHandler(render);
      }
    });
  } else {
    // Ältere Browser: klassischer handler
    event.intercept({ handler: render });
  }
});

Rendern für https://example.com/...

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell und bisher nur in neueren Chromium-Browsern verfügbar. Die Navigation API selbst fehlt in älteren Browsern ganz. Prüfen Sie daher immer, ob die Funktion vorhanden ist.
addHandler() dürfen Sie nur während der Precommit-Phase aufrufen. Nach dem Commit, etwa aus einem späten setTimeout heraus, wirft die Methode eine InvalidStateError-DOMException. Auch wenn die Navigation nicht mehr abgefangen werden kann, gibt es diesen Fehler.
Einen precommitHandler gibt es nur bei abbrechbaren Navigationen, wenn also event.cancelable true ist. Bei Vor-/Zurück-Navigationen über mehrere Dokumente hinweg steht er zum Beispiel nicht zur Verfügung.
Reichen Sie event.signal an fetch() weiter. So brechen Sie Anfragen ab, wenn der Nutzer mitten in der Navigation erneut navigiert.
Ein abgelehntes Promise im Handler lässt die gesamte Navigation fehlschlagen. Behandeln Sie Fehler bewusst.

Siehe auch

Navigation NavigationPrecommitController.redirect() NavigationPreloadManager.disable() NavigationPreloadManager.enable() Navigator.registerProtocolHandler()