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
pushState(state, unused)
pushState(state, unused, url)
Parameter
state
-
Das
state
-Objekt ist ein JavaScript-Objekt, das mit dem neuen Verlaufseintrag, der durchpushState()
erstellt wird, verknüpft ist. Immer wenn der Benutzer zu dem neuenstate
navigiert, wird einpopstate
-Ereignis ausgelöst, und diestate
-Eigenschaft des Ereignisses enthält eine Kopie desstate
-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 einesstate
-Objekts fest. Sie werfen eine Ausnahme, wenn Sie einstate
-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/oderlocalStorage
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 wirftpushState()
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 Standard # dom-history-pushstate-dev |
Browser-Kompatibilität
BCD tables only load in the browser