NavigationPrecommitController.redirect() — Methode · JavaScript-Referenz

Signatur

NavigationPrecommitController.prototype.redirect(url, options)

Beschreibung

redirect() gehört zur Navigation API. Die Methode steht nur innerhalb eines precommitHandler zur Verfügung, den du an NavigateEvent.intercept() übergibst. Der Handler bekommt ein NavigationPrecommitController-Objekt. Über dieses Objekt kannst du das Ziel der laufenden Navigation noch ändern, bevor die URL in der Adressleiste wechselt und ein Verlaufseintrag entsteht.

So kannst du Weiterleitungen auf der Client-Seite sauber umsetzen, zum Beispiel /konto → /login für nicht angemeldete Nutzer oder veraltete Routen → neue Routen. Die ursprüngliche URL taucht dabei nie im Verlauf auf. Ein nachträgliches navigation.navigate(..., { history: "replace" }) wäre dagegen sichtbar, und die Seite würde „springen“.

Mit dem optionalen Objekt options legst du den neuen Navigationsstatus fest (state, später lesbar über navigation.currentEntry.getState()). Außerdem bestimmst du, ob ein neuer Verlaufseintrag entsteht oder der aktuelle ersetzt wird (history). Du kannst redirect() im selben Handler mehrmals aufrufen, dann gilt der letzte Aufruf. Nach dem Commit (also im normalen handler) ist redirect() nicht mehr erlaubt.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Neues Ziel der Navigation. Relative URLs werden relativ zur Basis-URL des Dokuments aufgelöst. Die URL muss dieselbe Herkunft haben, das heißt, sie muss die aktuelle Dokument-URL ersetzen können.
$options	object	{}	Optionales Objekt mit Einstellungen für die Umleitung.
$options.state	any		Neuer Navigationsstatus für den Zieleintrag. Er muss mit dem structured clone-Algorithmus kopierbar sein. Lesen kannst du ihn später über `navigation.currentEntry.getState()`.
$options.history	"auto" \| "push" \| "replace"	"auto"	Legt fest, wie der Verlauf verändert wird. `"push"` legt einen neuen Eintrag an, `"replace"` ersetzt den aktuellen. Bei `"auto"` bleibt das Verhalten der ursprünglichen Navigation erhalten.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode ändert das Ziel der laufenden Navigation. Ob die Navigation fertig ist, erfährst du über navigation.transition.finished oder das Event navigatesuccess.

Beispiele

Geschützte Route auf die Login-Seite umleiten

const istAngemeldet = () => document.cookie.includes('session=');

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

  event.intercept({
    // Läuft VOR dem Commit – die URL ist noch nicht geändert
    precommitHandler: async (controller) => {
      if (!istAngemeldet()) {
        const login = new URL('/login', location.origin);
        login.searchParams.set('weiter', ziel.pathname);
        controller.redirect(login, { history: 'replace' });
      }
    },
    // Läuft NACH dem Commit – hier den Inhalt rendern
    handler: async () => {
      document.querySelector('main').textContent =
        `Seite: ${location.pathname}`;
    }
  });
});

Ohne Sitzung zeigt die Adressleiste direkt /login?weiter=%2Fkonto; /konto erscheint nie im Verlauf.

Veraltete Route umleiten und Status mitgeben

const umleitungen = new Map([
  ['/blog/alt-artikel', '/artikel/neu'],
  ['/hilfe', '/support']
]);

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

  event.intercept({
    precommitHandler: (controller) => {
      controller.redirect(neu, {
        state: { umgeleitetVon: pathname },
        history: 'auto'
      });
    },
    handler: async () => {
      const info = navigation.currentEntry.getState();
      console.log('Umgeleitet von', info?.umgeleitetVon);
    }
  });
});

navigation.navigate('/hilfe');

Umgeleitet von /hilfe

Funktionsprüfung und Fehlerbehandlung

const unterstuetzt =
  'navigation' in window &&
  'NavigationPrecommitController' in window;

navigation?.addEventListener('navigate', (event) => {
  if (!unterstuetzt || !event.canIntercept) return;

  event.intercept({
    precommitHandler: (controller) => {
      try {
        controller.redirect('https://fremde-domain.example/');
      } catch (err) {
        // SecurityError: andere Herkunft ist nicht erlaubt
        console.warn(err.name);
      }
    }
  });
});

SecurityError

// Wichtig · Fallstricke

Experimentell: Bisher gibt es die Methode nur in Chromium-Browsern (ab etwa Version 141). Prüfe vorher, ob sie verfügbar ist ('NavigationPrecommitController' in window), und sieh für andere Browser einen Weg ohne die Navigation API vor.
redirect() ist nur im precommitHandler erlaubt. Rufst du die Methode nach dem Commit auf, etwa im handler oder nach einem gespeicherten Verweis auf den Controller, wird ein InvalidStateError ausgelöst.
Bei Navigationen vom Typ "traverse" (Vor/Zurück) und "reload" ist keine Umleitung möglich. Auch dann wird ein InvalidStateError ausgelöst. Prüfe vorher event.navigationType.
Eine ungültige URL führt zu einem SyntaxError, eine URL mit anderer Herkunft zu einem SecurityError. Für Weiterleitungen auf andere Domains nimmst du location.assign() oder eine serverseitige Weiterleitung.
options.state muss strukturiert klonbar sein. Funktionen oder DOM-Knoten lösen einen DataCloneError aus.
Eine Weiterleitung auf der Client-Seite ist keine Zugriffskontrolle. Geschützte Daten musst du immer auf dem Server absichern.
Einen precommitHandler kannst du nur bei abbrechbaren Navigationen setzen (event.cancelable). Sonst löst schon intercept() einen Fehler aus.

Siehe auch

Navigation Navigation.navigate() NavigationPrecommitController.addHandler() NavigationPreloadManager.disable() NavigationPreloadManager.enable()