WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

history.replaceState — aktuellen Verlaufseintrag aktualisieren

history.replaceState aktualisiert den Zustand und optional die URL des aktuellen Verlaufseintrags, ohne die Seite neu zu laden. Es fügt keinen Eintrag hinzu und erzeugt daher keinen zusätzlichen Schritt für die Zurück-Schaltfläche.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

history.replaceState(data, unused)
history.replaceState(data, unused, url)

history.replaceState(data, unused, url) ersetzt den Zustand des aktuellen Eintrags; history.pushState fügt einen Eintrag hinzu. Dies ist eine durch HTML definierte Browser-API und keine Funktion einer bestimmten ECMAScript-Ausgabe. Dass Node 24 vorhanden ist, belegt nicht die Verfügbarkeit im Browser.

Übergib "" als erforderliches historisches Argument unused; es legt keinen Titel fest. Wird url weggelassen, bleibt die Adresse unverändert. Die Methode gibt undefined zurück. Sie lädt das Dokument nicht neu und löst selbst weder popstate noch hashchange aus.

data wird zur Speicherung strukturiert geklont und nicht als JSON serialisiert. Lies den gespeicherten Wert über history.state aus; spätere Änderungen am Eingabeobjekt ändern den gespeicherten Wert nicht. Funktionen und DOM-Knoten können auf diese Weise nicht gespeichert werden und verursachen DataCloneError.

Die Regeln zum Umschreiben der URL vergleichen die vorgeschlagene URL mit der aktuellen URL des Dokuments, nicht mit dessen Origin. So kann ein Dokument unter about:blank das Fragment seiner URL auch dann ändern, wenn es seinen Origin erbt. Eine unzulässige URL, ein nicht vollständig aktives Dokument oder Beschränkungen der Aufrufhäufigkeit können SecurityError verursachen. Verwende diese Methode, um die aktuelle Ansicht anzupassen, nicht um einen neuen Navigationsschritt zu erstellen.

Beispiele

(() => {
  const previousState = history.state;
  const previousURL = location.href;
  const previousLength = history.length;
  const data = { tab: "details" };
  const url = new URL(location.href);
  url.hash = "details";

  try {
    history.replaceState(data, "", url.href);
    data.tab = "changed";
    console.log(history.state.tab);
    console.log(location.hash);
    console.log(history.length === previousLength);
  } finally {
    history.replaceState(previousState, "", previousURL);
  }
})();

Ergebnis

details
#details
true

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen