Navigation.reload() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.reload(options)

Beschreibung

navigation.reload() ist das Gegenstück der Navigation API zu location.reload(). Die Methode stößt eine Neuladen-Navigation für den aktuellen Verlaufseintrag an. Anders als location.reload() kann sie über die Option state einen neuen Zustand am Eintrag hinterlegen und über info flüchtige Zusatzdaten an den navigate-Handler weitergeben.

Sie löst ein navigate-Ereignis mit navigationType === "reload" aus. Fängt eine Single-Page-Anwendung dieses Ereignis mit event.intercept() ab, gibt es kein echtes Neuladen des Dokuments. Stattdessen führt der eigene Handler das „Neuladen“ aus, z. B. indem er Daten neu abruft und die Ansicht neu rendert. Ohne Abfangen lädt der Browser die Seite ganz normal neu.

Zurückgegeben wird ein Objekt mit zwei Promises: committed wird erfüllt, sobald die sichtbare URL bzw. der Eintrag übernommen wurde. finished wird erfüllt, sobald alle Promises aus einem abgefangenen Handler erfüllt sind. So lässt sich gezielt auf das Ende des Neuladens warten, etwa um Ladeanzeigen auszublenden.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Objekt zur Steuerung des Neuladens.
$options.state	any		Neuer Zustand für den aktuellen Verlaufseintrag. Später über `navigation.currentEntry.getState()` abrufbar. Muss per Structured Clone kopierbar sein. Fehlt die Option, bleibt der bisherige Zustand erhalten.
$options.info	any	undefined	Beliebige flüchtige Daten, die nur im `navigate`-Ereignis als `event.info` ankommen. Sie werden nicht im Verlauf gespeichert.

Rückgabewert

Typ

{ committed: Promise<NavigationHistoryEntry>, finished: Promise<NavigationHistoryEntry> }

Beschreibung

Objekt mit zwei Promises: committed wird erfüllt, sobald der Eintrag übernommen ist. finished wird erfüllt, sobald die Navigation (inklusive abgefangener Handler) abgeschlossen ist. Wird die Navigation abgebrochen oder schlägt sie fehl, werden beide mit einer DOMException abgelehnt.

Beispiele

Einfaches Neuladen mit Feature-Erkennung

const reloadPage = () => {
  if ('navigation' in window) {
    navigation.reload();
  } else {
    // Fallback für Browser ohne Navigation API
    location.reload();
  }
};

document.querySelector('#reload-btn')?.addEventListener('click', reloadPage);

Zustand beim Neuladen aktualisieren

// Filtereinstellungen im Verlaufseintrag speichern und neu laden
const applyFilter = async (filter) => {
  const { finished } = navigation.reload({
    state: { ...navigation.currentEntry.getState(), filter }
  });
  await finished;
  console.log('Neuer Zustand:', navigation.currentEntry.getState());
};

applyFilter('nur-offene');

Neuer Zustand: { filter: 'nur-offene' }

Reload in einer SPA abfangen und Daten neu abrufen

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

  event.intercept({
    async handler() {
      const res = await fetch('/api/dashboard', { signal: event.signal });
      const data = await res.json();
      document.querySelector('#dashboard').textContent =
        `${data.items.length} Einträge (Quelle: ${event.info?.source ?? 'unbekannt'})`;
    }
  });
});

const refresh = async () => {
  try {
    await navigation.reload({ info: { source: 'refresh-button' } }).finished;
    console.log('Dashboard aktualisiert');
  } catch (err) {
    console.error('Neuladen abgebrochen:', err.name);
  }
};

refresh();

Dashboard aktualisiert

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Navigation API gibt es in Chromium-Browsern (Chrome, Edge, Opera) ab Version 102. Firefox und Safari unterstützen sie erst in sehr neuen Versionen (Firefox 147, Safari 26.2). Prüfe daher mit 'navigation' in window, ob sie vorhanden ist, und nutze sonst location.reload() als Fallback.
Der Wert von state muss per Structured Clone kopierbar sein. Funktionen oder DOM-Knoten führen zu einer DataCloneError-DOMException. Die Methode wirft dann nicht synchron, sondern die zurückgegebenen Promises werden abgelehnt.
Ist das Dokument nicht vollständig aktiv (z. B. ein entferntes iframe) oder wird gerade entladen, werden die Promises mit InvalidStateError abgelehnt.
Startet vor dem Abschluss eine neue Navigation, wird das Neuladen abgebrochen und die Promises werden mit AbortError abgelehnt. Fange das mit try/catch ab, damit keine unbehandelten Ablehnungen entstehen.
Ohne event.intercept() lädt der Browser das Dokument wirklich neu. Code nach await ... .finished läuft dann nicht mehr, weil die Seite entladen wird.
info wird nicht persistiert. Für Daten, die ein echtes Neuladen oder Vor-/Zurück-Navigation überstehen sollen, verwende state.

Siehe auch

Navigation Navigation.navigate() Location.reload() Navigation.forward() Navigation.back()