History.state — Eigenschaft · JavaScript-Referenz

Signatur

get History.prototype.state

Beschreibung

Die schreibgeschützte Eigenschaft history.state gibt den Wert zurück, der dem aktuellen Eintrag im Sitzungsverlauf zugeordnet ist. Dieser Wert wird über history.pushState(state, unused, url) oder history.replaceState(state, unused, url) gesetzt. Hat der aktuelle Eintrag keinen Zustand, ist der Wert null.

Besonders nützlich ist history.state in Single-Page-Anwendungen. Beim ersten Laden oder nach einem Neuladen der Seite wird kein popstate-Ereignis ausgelöst. Den Zustand kannst du dann direkt aus history.state lesen, statt auf ein Ereignis zu warten. Browser speichern den Zustand dauerhaft mit dem Verlaufseintrag. Deshalb bleibt er auch nach einem Neuladen der Seite oder beim Wiederherstellen des Tabs erhalten.

Der Zustand wird mit dem Structured-Clone-Algorithmus kopiert. history.state gibt also immer eine Kopie zurück und nie das Originalobjekt, das du an pushState() übergeben hast. Wenn du das zurückgegebene Objekt änderst, ändert sich der gespeicherte Zustand nicht. Dafür musst du replaceState() erneut aufrufen.

Rückgabewert

Typ

any

Beschreibung

Eine strukturierte Kopie des Zustandsobjekts des aktuellen Verlaufseintrags oder null, wenn kein Zustand gesetzt wurde.

Beispiele

Zustand setzen und auslesen

// Neuen Verlaufseintrag mit Zustand anlegen
history.pushState({ seite: 2, filter: 'neu' }, '', '?seite=2');

console.log(history.state);

// Zustand des aktuellen Eintrags ersetzen
history.replaceState({ ...history.state, filter: 'alt' }, '');
console.log(history.state.filter);

{ seite: 2, filter: 'neu' } alt

Zustand nach Neuladen der Seite wiederherstellen

// Beim Seitenstart gibt es kein popstate – daher history.state direkt lesen
const renderSeite = (state) => {
  const seite = state?.seite ?? 1;
  document.title = `Ergebnisse – Seite ${seite}`;
  console.log('Rendere Seite', seite);
};

renderSeite(history.state);

// Bei Zurück/Vorwärts erneut rendern
window.addEventListener('popstate', (event) => {
  // event.state entspricht history.state
  renderSeite(event.state);
});

Rendere Seite 1 (bzw. die gespeicherte Seite nach einem Reload)

Scroll-Position im Verlaufseintrag merken

const speichereScroll = () => {
  history.replaceState({ ...history.state, scrollY: window.scrollY }, '');
};

// Vor dem Wechsel zu einer neuen Ansicht Position sichern
const navigiere = (url) => {
  speichereScroll();
  history.pushState({ scrollY: 0 }, '', url);
  window.scrollTo(0, 0);
};

window.addEventListener('popstate', () => {
  window.scrollTo(0, history.state?.scrollY ?? 0);
});

Zurückgegebenes Objekt ist eine Kopie

const daten = { zaehler: 1 };
history.replaceState(daten, '');

console.log(history.state === daten);   // Kopie, nicht identisch

history.state.zaehler = 99;             // wirkt sich nicht aus
console.log(history.state.zaehler);

false 1

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie history.state = {...} wird ohne Fehlermeldung ignoriert (im Strict Mode wird ein TypeError ausgelöst). Zum Ändern verwendest du history.replaceState().
Nur klonbare Werte: Funktionen, DOM-Knoten, Symbole oder Klasseninstanzen mit Methoden lassen sich nicht serialisieren. pushState() bzw. replaceState() werfen dann eine DataCloneError-DOMException. Klasseninstanzen verlieren ihren Prototyp.
Größenbeschränkung: Browser begrenzen die Größe des serialisierten Zustands (in Firefox z. B. 16 MiB). Speichere nur kleine Daten wie IDs, Filter oder Scroll-Positionen, keine großen Datensätze.
Anfangswert: Bei einem normal geladenen Eintrag ist der Wert null. Lies ihn deshalb immer defensiv, z. B. mit history.state?.seite.
Sicherheit: Der Zustand bleibt in der Sitzung gespeichert und ist für jedes Skript desselben Ursprungs lesbar. Lege dort keine sensiblen Daten wie Tokens oder Passwörter ab.
Kompatibilität: Wird von allen modernen Browsern unterstützt (ab IE 10). Die neuere Navigation-API mit navigation.currentEntry.getState() ist eine Alternative, wird aber noch nicht überall unterstützt.

Siehe auch

History.pushState() History.replaceState() History History.length History.scrollRestoration