History: pushState()-Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die pushState()-Methode der History-Schnittstelle fügt einen Eintrag zum Sitzungsverlauf-Stack des Browsers hinzu.

Das state-Objekt ist ein JavaScript-Objekt, das mit dem neuen Verlaufseintrag, der durch pushState() erstellt wird, verknüpft ist. Immer wenn der Benutzer zu dem neuen state navigiert, wird ein popstate-Ereignis ausgelöst, und die state-Eigenschaft des Ereignisses enthält eine Kopie des state-Objekts des Verlaufs.

Das state-Objekt kann alles sein, was serialisierbar ist.

Hinweis: Einige Browser speichern state-Objekte auf der Festplatte des Benutzers, damit sie nach einem Neustart des Browsers wiederhergestellt werden können, und legen eine Größenbeschränkung für die serialisierte Darstellung eines state-Objekts fest. Sie werfen eine Ausnahme, wenn Sie ein state-Objekt übergeben, dessen serialisierte Darstellung größer als dieses Größenlimit ist. In Fällen, in denen Sie sicherstellen möchten, dass Sie mehr Speicherplatz als von einigen Browsern auferlegt erhalten, werden Sie ermutigt, sessionStorage und/oder localStorage zu verwenden.

unused

Dieser Parameter existiert aus historischen Gründen und kann nicht weggelassen werden; die Übergabe eines leeren Strings ist sicher gegenüber zukünftigen Änderungen der Methode.

url Optional

Die URL des neuen Verlaufseintrags. Beachten Sie, dass der Browser nach einem Aufruf von pushState() nicht versuchen wird, diese URL zu laden, aber möglicherweise später, beispielsweise nach einem Neustart des Browsers. Die neue URL muss nicht absolut sein; wenn sie relativ ist, wird sie relativ zur aktuellen URL aufgelöst. Die neue URL muss vom gleichen Ursprung wie die aktuelle URL sein; andernfalls wirft pushState() eine Ausnahme. Wenn dieser Parameter nicht angegeben ist, wird er auf die aktuelle URL des Dokuments gesetzt.

Rückgabewert

Keiner (undefined).

Ausnahmen

SecurityError DOMException: Wird geworfen, wenn das zugehörige Dokument nicht vollständig aktiv ist oder falls der bereitgestellte url-Parameter keine gültige URL darstellt. Browser drosseln auch die Navigation und können diesen Fehler werfen, eine Warnung generieren oder den Aufruf ignorieren, wenn er zu häufig aufgerufen wird.
DataCloneError DOMException: Wird geworfen, wenn der bereitgestellte state-Parameter nicht serialisierbar ist.

Beschreibung

In gewisser Weise ist ein Aufruf von pushState() ähnlich dem Setzen von window.location = "#foo", da beide ebenfalls einen weiteren Verlaufseintrag erzeugen und aktivieren, der mit dem aktuellen Dokument verknüpft ist. Aber pushState() bietet einige Vorteile:

Die neue URL kann jede URL im gleichen Ursprung wie die aktuelle URL sein. Im Gegensatz dazu bleibt man bei window.location nur im selben Dokument, wenn man nur den Hash ändert.
Das Ändern der URL der Seite ist optional. Im Gegensatz zum Setzen von window.location = "#foo";, das nur einen neuen Verlaufseintrag erzeugt, wenn der aktuelle Hash nicht #foo ist.
Sie können beliebige Daten mit Ihrem neuen Verlaufseintrag verknüpfen. Beim Hash-basierten Ansatz müssen Sie alle relevanten Daten in eine kurze Zeichenkette kodieren.

Beachten Sie, dass pushState() niemals ein hashchange-Ereignis auslöst, selbst wenn sich die neue URL nur im Hash von der alten URL unterscheidet.

Beispiele

Dies erstellt einen neuen Verlaufseintrag des Browsers, wobei der state und die url festgelegt werden.

JavaScript

const state = { page_id: 1, user_id: 5 };
const url = "hello-world.html";

history.pushState(state, "", url);

Ändern eines Abfrageparameters

const url = new URL(location);
url.searchParams.set("foo", "bar");
history.pushState({}, "", url);

Spezifikationen

Specification
HTML # dom-history-pushstate-dev

Browser-Kompatibilität

BCD tables only load in the browser