Navigation.updateCurrentEntry() — Methode · JavaScript-Referenz

Signatur

Navigation.prototype.updateCurrentEntry(options)

Beschreibung

Die Methode updateCurrentEntry() des Navigation-Interfaces ersetzt den gespeicherten Zustand (state) des aktuellen Verlaufseintrags, also von navigation.currentEntry. Die URL bleibt gleich, es gibt kein navigate-Event und der Verlauf bekommt keinen neuen Eintrag.

Sinnvoll ist das bei Zuständen, die zur aktuellen Seite gehören, aber in der URL nichts zu suchen haben. Beispiele sind aufgeklappte Bereiche, die Scrollposition in einer Liste, der Zwischenstand eines Formulars oder die gewählte Tab-Ansicht. Kehrt der Nutzer später per Zurück/Vorwärts zu diesem Eintrag zurück, liest man den Zustand mit navigation.currentEntry.getState() wieder aus.

Innerhalb der Navigation API entspricht das in etwa history.replaceState(state, "") ohne URL-Änderung. Der Zustand wird mit dem structured clone-Algorithmus kopiert. Erlaubt sind also Objekte, Arrays, Map, Set, Date usw., aber keine Funktionen und keine DOM-Knoten. Nach dem Aufruf feuert navigation das Event currententrychange. Dessen navigationType ist dabei null.

Parameter

Name	Typ	Default	Beschreibung
$options Pflicht	Object		Options-Objekt. Es muss übergeben werden.
$options.state Pflicht	any		Der neue Zustand für den aktuellen Eintrag. Er muss per structured clone kopierbar sein und ersetzt den bisherigen Zustand vollständig. Es wird nichts zusammengeführt.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Den neuen Zustand liest man über navigation.currentEntry.getState() aus.

Beispiele

Filterzustand im aktuellen Eintrag speichern

// Filter einer Produktliste merken, ohne die URL zu ändern
const saveFilter = (filter) => {
  navigation.updateCurrentEntry({
    state: { ...navigation.currentEntry.getState(), filter }
  });
};

saveFilter({ category: 'buecher', sort: 'preis' });
console.log(navigation.currentEntry.getState());

{ filter: { category: 'buecher', sort: 'preis' } }

Zustand beim Zurücknavigieren wiederherstellen

const restoreUi = () => {
  const state = navigation.currentEntry.getState() ?? {};
  document.querySelector('#details').open = Boolean(state.detailsOpen);
};

// Beim Auf- und Zuklappen den Zustand im Eintrag speichern
document.querySelector('#details').addEventListener('toggle', (event) => {
  navigation.updateCurrentEntry({
    state: { ...navigation.currentEntry.getState(), detailsOpen: event.target.open }
  });
});

// Nach jedem Wechsel des aktuellen Eintrags (z. B. Zurück-Taste) die Oberfläche anpassen
navigation.addEventListener('currententrychange', restoreUi);
restoreUi();

Funktionsprüfung und Fehlerbehandlung

const safeUpdateState = (state) => {
  if (!('navigation' in window)) {
    // Rückfall auf die History API
    history.replaceState(state, '');
    return;
  }
  try {
    navigation.updateCurrentEntry({ state });
  } catch (err) {
    // DataCloneError: Zustand ist nicht kopierbar
    // InvalidStateError: Dokument nicht aktiv oder wird gerade entladen
    console.error(err.name, err.message);
  }
};

safeUpdateState({ scrollY: window.scrollY });
safeUpdateState({ callback: () => {} });

DataCloneError ... could not be cloned.

// Wichtig · Fallstricke

Vollständiges Ersetzen: state überschreibt den bisherigen Zustand komplett. Um Teile zu erhalten, den alten Zustand zuerst per getState() lesen und dann mit dem Spread-Operator zusammenführen.
Ausnahmen: Ein DataCloneError tritt auf, wenn der Zustand nicht kopierbar ist, etwa bei Funktionen, DOM-Knoten oder Symbolen. Ein InvalidStateError tritt auf, wenn das Dokument nicht vollständig aktiv ist, gerade entladen wird oder es keinen currentEntry gibt, zum Beispiel auf about:blank direkt nach dem Öffnen.
Kein navigate-Event: Es wird nur currententrychange ausgelöst. Wer gleichzeitig die URL ändern will, nimmt navigation.navigate(url, { state, history: 'replace' }).
Nur innerhalb der Sitzung: Der Zustand bleibt für diesen Verlaufseintrag erhalten, auch nach einem Neuladen. Er gilt aber nicht für neue Tabs und gehört nicht in die URL. Teilbare Zustände sollten deshalb in die URL, nicht in state.
Größe: Browser können sehr große Zustandsobjekte begrenzen. Speichere daher nur kleine, serialisierbare Daten.
Kompatibilität: Die Navigation API gibt es in Chromium-Browsern seit Version 102. In Firefox und Safari ist sie erst in aktuellen Versionen dazugekommen. Deshalb vorher mit 'navigation' in window prüfen und als Rückfall history.replaceState() nutzen.

Siehe auch

Navigation Navigation.currentEntry NavigationHistoryEntry.getState() Navigation.navigate() Navigation.reload() History.replaceState()