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.

Syntax

js
pushState(state, unused)
pushState(state, unused, url)

Parameter

state

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

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

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

Ändern eines Abfrageparameters

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

Spezifikationen

Specification
HTML
# dom-history-pushstate-dev

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
pushState
Whether the unused parameter is used
DeprecatedNon-standard

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
See implementation notes.

Siehe auch