History — Schnittstelle · JavaScript-Referenz

Signatur

interface History

Beschreibung

Das Interface History gehört zur History API und steht für den Sitzungsverlauf eines Browserkontexts. Gemeint sind die Seiten, die im aktuellen Tab oder Frame besucht wurden. Einen Konstruktor gibt es nicht. Die einzige Instanz erreicht man über window.history.

Mit dem Interface lässt sich im Verlauf vor- und zurückspringen: back(), forward() und go(delta). Man kann aber auch neue Einträge anlegen (pushState()) oder den aktuellen Eintrag ersetzen (replaceState()), ohne die Seite neu zu laden. Darauf bauen Single-Page-Anwendungen (SPAs) und clientseitige Router auf: Sie ändern die URL in der Adressleiste, laden die Inhalte selbst per JavaScript nach, und die Zurück-Taste funktioniert trotzdem wie gewohnt.

Wichtige Eigenschaften:

length: Anzahl der Einträge im Sitzungsverlauf, den aktuellen Eintrag mitgezählt (nur lesbar).
state: Das Zustandsobjekt des aktuellen Eintrags, das per pushState()/replaceState() gesetzt wurde, sonst null.
scrollRestoration: "auto" oder "manual". Legt fest, ob der Browser die Scroll-Position beim Navigieren im Verlauf selbst wiederherstellt.

Wechselt der Nutzer (oder back()/go()) zwischen Einträgen, die im selben Dokument per pushState() angelegt wurden, löst der Browser auf window das Ereignis popstate aus. pushState() und replaceState() selbst lösen kein popstate aus. Die Anwendung muss ihre Oberfläche nach diesen Aufrufen also selbst aktualisieren.

Parameter

Name	Typ	Default	Beschreibung
$state Pflicht	any (strukturiert klonbar)		Bei `pushState(state, unused, url)` und `replaceState(…)`: Zustandsobjekt, das dem Verlaufseintrag zugeordnet wird. Es muss mit dem Structured-Clone-Algorithmus kopierbar sein (keine Funktionen, keine DOM-Knoten). Wenn nichts gebraucht wird, `null` übergeben.
$unused Pflicht	string	""	Früher `title`. Wird von allen Browsern ignoriert, muss aus Kompatibilitätsgründen aber übergeben werden, üblicherweise als leere Zeichenkette `""`.
$url	string \| URL	aktuelle URL	Neue URL für den Verlaufseintrag, relativ oder absolut. Sie muss denselben Ursprung (Origin) haben wie das aktuelle Dokument, sonst wird ein `SecurityError` geworfen. Die Seite wird dabei nicht geladen.
$delta	number	0	Bei `go(delta)`: relative Position im Verlauf. `-1` entspricht `back()`, `1` entspricht `forward()`. `0` oder kein Wert lädt die aktuelle Seite neu.

Rückgabewert

Typ

History

Beschreibung

window.history liefert das History-Objekt des aktuellen Browserkontexts. Die Methoden back(), forward(), go(), pushState() und replaceState() geben undefined zurück. Die Navigation mit back()/forward()/go() läuft asynchron ab.

Beispiele

Verlauf lesen und navigieren

// Anzahl der Einträge im aktuellen Tab
console.log(`Einträge im Verlauf: ${history.length}`);

// Zurück-Button in der eigenen Oberfläche
document.querySelector('#zurueck')?.addEventListener('click', () => {
  history.back(); // entspricht history.go(-1)
});

// Zwei Schritte vorwärts
document.querySelector('#vor2')?.addEventListener('click', () => {
  history.go(2);
});

Einträge im Verlauf: 3

Minimaler SPA-Router mit pushState und popstate

const ansichten = {
  '/': () => '<h1>Start</h1>',
  '/produkte': () => '<h1>Produkte</h1>',
  '/kontakt': () => '<h1>Kontakt</h1>'
};

const render = (pfad) => {
  const ansicht = ansichten[pfad] ?? (() => '<h1>404</h1>');
  document.querySelector('#app').innerHTML = ansicht();
};

// Interne Links abfangen
document.addEventListener('click', (event) => {
  const link = event.target.closest('a[data-intern]');
  if (!link) return;
  event.preventDefault();
  const pfad = new URL(link.href).pathname;
  history.pushState({ pfad }, '', pfad); // neuer Verlaufseintrag, kein Neuladen
  render(pfad); // pushState löst kein popstate aus, daher selbst rendern
});

// Zurück/Vor-Taste des Browsers
window.addEventListener('popstate', (event) => {
  render(event.state?.pfad ?? location.pathname);
});

// Startzustand setzen, damit history.state nicht null ist
history.replaceState({ pfad: location.pathname }, '', location.pathname);
render(location.pathname);

Filterzustand in der URL speichern, ohne Verlaufseinträge anzuhäufen

const setzeFilter = (kategorie, seite) => {
  const url = new URL(location.href);
  url.searchParams.set('kategorie', kategorie);
  url.searchParams.set('seite', String(seite));
  // replaceState: aktueller Eintrag wird ersetzt, die Zurück-Taste bleibt sauber
  history.replaceState({ kategorie, seite }, '', url);
};

setzeFilter('buecher', 2);
console.log(location.search);
console.log(history.state);

?kategorie=buecher&seite=2 { kategorie: 'buecher', seite: 2 }

Scroll-Wiederherstellung selbst steuern

if ('scrollRestoration' in history) {
  history.scrollRestoration = 'manual';
}

window.addEventListener('popstate', (event) => {
  const y = event.state?.scrollY ?? 0;
  window.scrollTo({ top: y, behavior: 'instant' });
});

// Vor dem Wechsel die aktuelle Position im Eintrag sichern
const navigiere = (pfad) => {
  history.replaceState({ ...history.state, scrollY: window.scrollY }, '');
  history.pushState({ scrollY: 0 }, '', pfad);
};

Siehe auch

Attr HID Headers MIDIPort Sensor