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 des History Interfaces fügt einen Eintrag zum Sitzungsverlauf-Stack des Browsers hinzu.

Das state Objekt ist ein JavaScript-Objekt, das mit dem neuen Verlaufseintrag verbunden ist, der durch pushState() erstellt wird. Jedes Mal, 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 Verlaufseintrags.

Das state Objekt kann alles sein, das serialisiert werden kann.

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 ein state Objekt übergeben wird, dessen serialisierte Darstellung größer als diese Größenbeschränkung ist. In Fällen, in denen Sie sicherstellen möchten, dass Ihnen mehr Speicherplatz zur Verfügung steht, als einige Browser möglicherweise festlegen, wird empfohlen, 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 künftige Änderungen der Methode.

url Optional

Die URL des neuen Verlaufseintrags. Beachten Sie, dass der Browser nicht versuchen wird, diese URL nach einem Aufruf von pushState() zu laden, sondern möglicherweise später versuchen könnte, die URL zu laden, beispielsweise nachdem der Benutzer den Browser neu gestartet hat. 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 Origin wie die aktuelle URL stammen; andernfalls wird pushState() eine Ausnahme auslösen. Wenn dieser Parameter nicht angegeben ist, wird er auf die aktuelle URL des Dokuments gesetzt.

Rückgabewert

Keiner (undefined).

Ausnahmen

SecurityError DOMException: Wird ausgelöst, wenn das zugehörige Dokument nicht vollständig aktiv ist, wenn der bereitgestellte url Parameter keine gültige URL ist oder wenn die Methode zu häufig aufgerufen wird.
DataCloneError DOMException: Wird ausgelöst, wenn der bereitgestellte state Parameter nicht serialisierbar ist.

Beschreibung

In gewisser Weise ist der Aufruf von pushState() ähnlich wie das Setzen von window.location = "#foo", da beide auch einen weiteren Verlaufseintrag erstellen und aktivieren, der mit dem aktuellen Dokument verbunden ist. pushState() hat jedoch einige Vorteile:

Die neue URL kann jede beliebige URL im gleichen Ursprung wie die aktuelle URL sein. Im Kontrast dazu bleibt man beim Setzen von window.location nur dann beim selben Dokument, wenn man nur den Hash ändert.
Das Ändern der Seiten-URL ist optional. Im Gegensatz dazu erstellt window.location = "#foo"; nur dann einen neuen Verlaufseintrag, wenn der aktuelle Hash nicht #foo ist.
Sie können beliebige Daten mit Ihrem neuen Verlaufseintrag verknüpfen. Bei dem Hash-basierten Ansatz müssen Sie alle relevanten Daten in einen kurzen String codieren.

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 im Browser, indem state und url gesetzt 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

History: pushState() Methode

Syntax

Parameter