NavigationHistoryEntry.getState() — Methode · JavaScript-Referenz

Signatur

NavigationHistoryEntry.prototype.getState()

Beschreibung

Die Methode getState() eines NavigationHistoryEntry-Objekts liest den Zustand aus, der beim Anlegen oder Aktualisieren des Eintrags gespeichert wurde. Das geschieht zum Beispiel über navigation.navigate(url, { state }), navigation.reload({ state }) oder navigation.updateCurrentEntry({ state }). So kann man anwendungsspezifische Daten wie Scrollposition, Filtereinstellungen oder Formularentwürfe an einen Eintrag im Verlauf binden, ohne sie in der URL abzulegen.

Der Zustand wird mit dem Structured-Clone-Algorithmus gespeichert. Deshalb liefert jeder Aufruf von getState() eine neue Kopie. Änderst du das zurückgegebene Objekt, ändert sich der gespeicherte Zustand nicht. Wenn du ihn wirklich ändern willst, musst du für den aktuellen Eintrag navigation.updateCurrentEntry({ state }) aufrufen.

Anders als history.state kannst du damit auch den Zustand anderer Einträge lesen, etwa über navigation.entries(), solange sie zum selben Dokument-Ursprung gehören. Typischerweise liest man den Zustand im navigate-Event aus (über event.destination.getState()) oder nach einem Wechsel des Eintrags über navigation.currentEntry.getState().

Rückgabewert

Typ

any

Beschreibung

Eine strukturierte Kopie des gespeicherten Zustands. Wurde nie ein Zustand gesetzt, ist der Wert undefined.

Beispiele

Zustand beim Navigieren setzen und auslesen

// Neue Navigation mit Zustand anstoßen
await navigation.navigate('/produkte?seite=2', {
  state: { filter: 'schuhe', sortierung: 'preis' }
}).committed;

const state = navigation.currentEntry.getState();
console.log(state.filter, state.sortierung);

schuhe preis

Zustand ist eine Kopie – Änderungen explizit speichern

navigation.updateCurrentEntry({ state: { scrollY: 0 } });

const state = navigation.currentEntry.getState();
state.scrollY = 500; // ändert nur die Kopie
console.log(navigation.currentEntry.getState().scrollY); // 0

// Richtig: Zustand explizit aktualisieren
navigation.updateCurrentEntry({ state: { ...state } });
console.log(navigation.currentEntry.getState().scrollY); // 500

0 500

Zustand des Ziel-Eintrags im navigate-Event auswerten

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

  // Bei Traverse (Zurück/Vor) liefert destination.getState() den gespeicherten Zustand
  const zielState = event.destination.getState();

  event.intercept({
    async handler() {
      await renderSeite(new URL(event.destination.url).pathname);
      if (zielState?.scrollY !== undefined) {
        window.scrollTo(0, zielState.scrollY);
      }
    }
  });
});

async function renderSeite(pfad) {
  document.querySelector('main').textContent = `Seite: ${pfad}`;
}

Zustände aller Einträge auflisten

const uebersicht = navigation.entries().map((entry) => ({
  index: entry.index,
  url: entry.url,
  state: entry.getState() ?? null
}));
console.table(uebersicht);

// Wichtig · Fallstricke

Kopie statt Referenz: Jeder Aufruf erzeugt einen neuen Klon. Direkte Änderungen am Ergebnis werden nicht gespeichert. Speichere sie über navigation.updateCurrentEntry(). Wenn du getState() sehr oft mit großen Objekten aufrufst, kostet jedes Klonen Leistung. Lege das Ergebnis deshalb bei Bedarf in einer Variablen ab.
Nur klonbare Werte: Funktionen, DOM-Knoten und Ähnliches lassen sich nicht speichern. Beim Setzen wird dann ein DataCloneError ausgelöst.
Kein Zusammenhang mit history.state: Der Zustand der Navigation API ist von history.pushState() bzw. history.state getrennt. Beide Mechanismen teilen ihre Daten nicht.
Gehört der Eintrag nicht mehr zum aktuellen Dokument (Eigenschaft index ist -1), liefert getState() undefined.
Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102. Firefox (ab 147) und Safari (ab 26.2) unterstützen sie erst seit Kurzem. Prüfe die Unterstützung mit if ('navigation' in window) und sieh für ältere Browser history.state als Ersatz vor.
Datenschutz: Der Zustand wird im Sitzungsverlauf gespeichert und kann Neuladen und Browser-Wiederherstellung überdauern. Speichere darin keine sensiblen Daten.

Siehe auch

Navigation.navigate() History.state new NavigationCurrentEntryChangeEvent() NavigationDestination.getState() NavigationPreloadManager.getState()