NavigateEvent.userInitiated — Eigenschaft · JavaScript-Referenz

Signatur

NavigateEvent.userInitiated

Beschreibung

Die schreibgeschützte Eigenschaft userInitiated des NavigateEvent-Interfaces ist true, wenn der Benutzer die Navigation selbst ausgelöst hat. Typische Fälle sind ein Klick auf einen Link, das Absenden eines Formulars oder die Zurück- und Vorwärts-Schaltflächen des Browsers. Wird die Navigation dagegen per Skript angestoßen, etwa mit navigation.navigate(), location.href = … oder history.back(), ist der Wert false.

Die Eigenschaft ist vor allem in Single-Page-Anwendungen nützlich, die Navigationen über das navigate-Ereignis von window.navigation abfangen. So kannst du Benutzeraktionen anders behandeln als interne Weiterleitungen: Nur bei echten Benutzeraktionen fragst du „Ungespeicherte Änderungen verwerfen?“, setzt den Fokus zurück, springst an den Seitenanfang oder erfasst die Navigation in der Analyse. Programmatische Umleitungen wie ein Login-Redirect laufen dagegen still im Hintergrund.

Weil userInitiated nur eine Eigenschaft ist, nimmt sie keine Parameter entgegen. Der Wert steht beim Erzeugen des Ereignisses fest und lässt sich nicht ändern.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Benutzer die Navigation ausgelöst hat (Link, Formular, Browser-Bedienelemente), sonst false.

Beispiele

Herkunft der Navigation protokollieren

navigation.addEventListener('navigate', (event) => {
  const quelle = event.userInitiated ? 'Benutzer' : 'Skript';
  console.log(`Navigation nach ${event.destination.url} durch: ${quelle}`);
});

// Programmatische Navigation zum Testen
navigation.navigate('/profil');

Navigation nach https://example.com/profil durch: Skript

Nur bei Benutzeraktionen vor ungespeicherten Änderungen warnen

let hatUngespeicherteAenderungen = true;

navigation.addEventListener('navigate', (event) => {
  // Interne Weiterleitungen nicht blockieren
  if (!event.userInitiated || !hatUngespeicherteAenderungen) return;

  // Nur abbrechen, wenn das Ereignis abbrechbar ist
  if (event.cancelable && !confirm('Ungespeicherte Änderungen verwerfen?')) {
    event.preventDefault();
  }
});

SPA-Routing: Scroll und Fokus nur bei Benutzernavigation zurücksetzen

const renderRoute = async (url) => {
  const res = await fetch(`/partials${new URL(url).pathname}`);
  document.querySelector('main').innerHTML = await res.text();
};

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

  event.intercept({
    scroll: 'manual',
    focusReset: event.userInitiated ? 'after-transition' : 'manual',
    handler: async () => {
      await renderRoute(event.destination.url);
      if (event.userInitiated) event.scroll();
    }
  });
});

// Wichtig · Fallstricke

Browser-Unterstützung: Die Navigation API gibt es seit Chrome/Edge 102. Firefox und Safari unterstützen sie erst in neueren Versionen. Prüfe vor der Nutzung mit 'navigation' in window, ob sie verfügbar ist, und sieh eine Ausweichlösung vor, z. B. die History API.
Nicht jede Benutzeraktion zählt: Skriptcode, der einen Klick nachahmt (link.click()) oder Navigationen wie location.assign() und history.back() aufruft, gilt in der Regel als nicht benutzerinitiiert. Das gilt auch, wenn der Aufruf in einem Klick-Handler steht.
Nicht als Sicherheitsmerkmal verwenden: Der Wert hilft bei der Gestaltung der Oberfläche, ersetzt aber keine Prüfung auf dem Server oder der Berechtigungen.
Zurück/Vorwärts: Nutzt der Benutzer die Browser-Schaltflächen, ist userInitiated true. Solche Traversal-Navigationen sind aber oft nicht abbrechbar (cancelable ist false). Deshalb ist preventDefault() dort wirkungslos.

Siehe auch

Navigation NavigateEvent.destination NavigateEvent.canIntercept NavigateEvent.formData NavigateEvent.signal