NavigateEvent.canIntercept — Eigenschaft · JavaScript-Referenz

Signatur

NavigateEvent.canIntercept

Beschreibung

Die schreibgeschützte Eigenschaft canIntercept des NavigateEvent-Interfaces gibt an, ob eine Navigation mit event.intercept() abgefangen werden darf. Beim Abfangen lädt der Browser kein neues Dokument. Er tauscht nur die URL des aktuellen Dokuments aus, und Ihr eigener Code (z. B. ein SPA-Router) rendert den neuen Inhalt.

Der Wert ist true, wenn sich die Ziel-URL als URL des aktuellen Dokuments eintragen lässt. Das ist ungefähr dieselbe Regel wie bei history.pushState(). Konkret gilt:

Schema, Host, Port, Benutzername und Passwort müssen gleich sein, also gleicher Ursprung (Same-Origin).
Bei Schemata außer http/https (z. B. file:) müssen in der Regel auch die Pfade übereinstimmen.
Navigationen durch den Verlauf (navigationType === "traverse") lassen sich nur abfangen, wenn sie im selben Dokument bleiben. Springt der Verlauf zu einem Eintrag, der zu einem anderen Dokument gehört, ist der Wert false.

In der Praxis prüfen Sie canIntercept gleich am Anfang jedes navigate-Handlers, bevor Sie intercept() aufrufen. Links zu fremden Domains führen dann wie gewohnt zu einem normalen Seitenwechsel. Nur interne Routen übernimmt der clientseitige Router.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn event.intercept() für diese Navigation erlaubt ist, sonst false.

Beispiele

Einfacher SPA-Router mit canIntercept-Prüfung

navigation.addEventListener("navigate", (event) => {
  // Fremde Ursprünge oder Wechsel zu anderen Dokumenten nicht anfassen
  if (!event.canIntercept) return;

  // Downloads, Fragment-Sprünge und Formular-POSTs dem Browser überlassen
  if (event.hashChange || event.downloadRequest !== null || event.formData) return;

  const url = new URL(event.destination.url);

  if (url.pathname.startsWith("/artikel/")) {
    event.intercept({
      async handler() {
        const res = await fetch(`/api${url.pathname}`);
        const daten = await res.json();
        document.querySelector("main").textContent = daten.titel;
      }
    });
  }
});

Wert für verschiedene Ziele protokollieren

navigation.addEventListener("navigate", (event) => {
  console.log(
    event.navigationType,
    event.destination.url,
    "abfangbar:", event.canIntercept
  );
});

// Auf https://example.com/start ausgeführt:
navigation.navigate("/profil");          // gleicher Ursprung
// navigation.navigate("https://andere-domain.de/"); // fremder Ursprung

push https://example.com/profil abfangbar: true (beim fremden Ursprung: push https://andere-domain.de/ abfangbar: false)

Funktionsprüfung und sicherer Aufruf von intercept()

if ("navigation" in window) {
  navigation.addEventListener("navigate", (event) => {
    if (!event.canIntercept) {
      console.info("Normale Navigation:", event.destination.url);
      return;
    }
    try {
      event.intercept({
        handler: async () => {
          document.title = `Seite: ${new URL(event.destination.url).pathname}`;
        }
      });
    } catch (err) {
      console.error("Abfangen fehlgeschlagen:", err.name);
    }
  });
} else {
  console.warn("Navigation API nicht verfügbar – Fallback auf History API");
}

// Wichtig · Fallstricke

SecurityError: Wenn Sie event.intercept() aufrufen, obwohl canIntercept den Wert false hat, wirft der Browser eine DOMException vom Typ SecurityError. Prüfen Sie den Wert deshalb immer vorher.
Nicht dasselbe wie cancelable: canIntercept sagt nur, ob die Navigation abgefangen werden darf. Ob sie sich mit preventDefault() abbrechen lässt, steht in event.cancelable. Beide Werte können unabhängig voneinander true oder false sein.
Zurück/Vor zu einem anderen Dokument: Geht die Verlaufsnavigation zu einem Eintrag, der zu einem anderen Dokument gehört, ist der Wert false, auch wenn beide Seiten denselben Ursprung haben.
true heißt nicht automatisch „abfangen“: Auch bei true sollten Sie Downloads (downloadRequest), reine Fragment-Sprünge (hashChange) und oft auch Formular-Absendungen (formData) dem Browser überlassen.
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üfen Sie die Unterstützung mit "navigation" in window und bauen Sie für ältere Browser einen Fallback über die History API.

Siehe auch

NavigateEvent.hashChange NavigateEvent.info NavigateEvent.navigationType NavigateEvent.sourceElement NavigateEvent.userInitiated