Window: popstate Ereignis

Syntax

Verwenden Sie den Ereignisnamen in Methoden wie addEventListener() oder setzen Sie eine Ereignis-Handler-Eigenschaft.

addEventListener("popstate", (event) => { })

onpopstate = (event) => { }

Ereignistyp

Ein PopStateEvent. Erbt von Event.

Ereigniseigenschaften

PopStateEvent.state Schreibgeschützt

Gibt eine Kopie der Informationen zurück, die pushState() oder replaceState() bereitgestellt wurden.

Alias der Ereignis-Handler

Zusätzlich zur Window-Schnittstelle ist die Ereignis-Handler-Eigenschaft onpopstate auch auf den folgenden Elementen verfügbar:

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

Der Verlaufstapel

Wenn der zu aktivierende Verlaufseintrag durch einen Aufruf von history.pushState() erstellt wurde oder durch einen Aufruf von history.replaceState() beeinflusst wurde, enthält die state-Eigenschaft des popstate-Ereignisses eine Kopie des Statusobjekts des Verlaufseintrags.

Diese Methoden und ihre entsprechenden Ereignisse können verwendet werden, um Daten zum Verlaufstapel hinzuzufügen, die zur Rekonstruktion einer dynamisch generierten Seite oder zur Änderung des Zustands der präsentierten Inhalte verwendet werden können, während im selben Document verbleibt.

Beachten Sie, dass durch den bloßen Aufruf von history.pushState() oder history.replaceState() kein popstate-Ereignis ausgelöst wird. Das popstate-Ereignis wird durch eine Browseraktion wie einen Klick auf die Vorwärts- oder Rückwärts-Schaltfläche (oder durch den Aufruf von history.back() oder history.forward() in JavaScript) ausgelöst.

Wann popstate gesendet wird

Es ist wichtig, zunächst zu verstehen, dass — um unerwünschte Pop-ups zu bekämpfen — Browser das popstate-Ereignis möglicherweise überhaupt nicht auslösen, es sei denn, die Seite wurde interagiert.

Dieser Abschnitt beschreibt die Schritte, die Browser in den Fällen befolgen, in denen sie das popstate-Ereignis potenziell auslösen (d.h. in den Fällen, in denen die Seite interagiert wurde).

Wenn eine Navigation erfolgt — entweder durch die Auslösung der Zurück-Schaltfläche des Browsers durch den Benutzer oder auf andere Weise —, befindet sich das popstate-Ereignis gegen Ende des Prozesses zum Navigieren zur neuen Position. Es passiert nachdem die neue Position geladen (falls nötig), angezeigt und sichtbar gemacht wurde und so weiter — nachdem das pageshow-Ereignis gesendet wurde, aber bevor die gespeicherten Benutzerdaten wiederhergestellt werden und das hashchange-Ereignis gesendet wird.

Um besser zu verstehen, wann das popstate-Ereignis ausgelöst wird, betrachten Sie diese vereinfachte Abfolge von Ereignissen, die auftritt, wenn sich der aktuelle Verlaufseintrag aufgrund entweder der Navigation des Benutzers auf der Website oder der programmgesteuerten Durchquerung des Verlaufs ändert. Hier ändert der Übergang den aktuellen Verlaufseintrag zu einem, den wir als new-entry bezeichnen werden. Der Verlaufssitzungsstapel der aktuellen Seite wird als current-entry bezeichnet.

1. Wenn new-entry derzeit kein vorhandenes Document enthält, rufen Sie den Inhalt ab und erstellen Sie sein Document, bevor Sie fortfahren. Dies wird schließlich Ereignisse wie DOMContentLoaded und load an das Window senden, das das Dokument enthält, aber die untenstehenden Schritte werden weiterhin ausgeführt.
2. Wenn der Titel von current-entry nicht mit einer der Methoden der History API (pushState() oder replaceState()) gesetzt wurde, setzen Sie den Eintrags-Titel auf die Zeichenfolge zurück, die von seinem document.title-Attribut zurückgegeben wird.
3. Wenn der Browser die Statusinformationen speichern möchte, die er mit current-entry vor der Navigation von ihm weg speichert, tut er dies. Der Eintrag soll jetzt „persistierten Benutzerstatus“ haben. Zu den Informationen, die der Browser möglicherweise zum Verlaufs Sitzungseintrag hinzufügt, gehören z. B. die Scrollposition des Dokuments, die Werte der Formulareingaben und andere solche Daten.
4. Wenn new-entry ein anderes Document-Objekt als current-entry aufweist, wird der Browsing-Kontext so aktualisiert, dass seine document-Eigenschaft auf das Dokument verweist, auf das sich new-entry bezieht, und der Kontextname wird aktualisiert, um dem Kontextnamen des jetzt aktuellen Dokuments zu entsprechen.
5. Jedes Formularelement innerhalb des Document von new-entry, das autocomplete konfiguriert hat, wobei der Name seines Autofill-Felds auf off gesetzt ist, wird zurückgesetzt. Siehe Das HTML-Autocomplete-Attribut, um mehr über die Namen von Autocomplete-Feldern und die Funktionsweise von Autocomplete zu erfahren.
6. Wenn das Dokument von new-entry bereits vollständig geladen und bereit ist — d.h. sein readyState ist complete — und das Dokument noch nicht sichtbar ist, wird es sichtbar gemacht und das pageshow-Ereignis wird mit dem PageTransitionEvent an das Dokument gesendet, wobei das Attribut persisted auf true gesetzt ist.
7. Die URL des Dokuments wird auf die von new-entry gesetzt.
8. Wenn die Verlaufstraversierung mit aktivierter Ersetzung durchgeführt wird, wird der Eintrag unmittelbar vor dem Ziel-Eintrag (unter Berücksichtigung des delta-Parameters in Methoden wie go()) aus dem Verlaufstapel entfernt.
9. Wenn new-entry keinen gespeicherten Benutzerstatus hat und das Fragment seiner URL nicht null ist, wird das Dokument zu diesem Fragment gescrollt.
10. Als nächstes wird current-entry auf new-entry gesetzt. Der Ziel-Eintrag wird nun als aktuell angesehen.
11. Wenn new-entry serialisierte Statusinformationen gespeichert hat, die mit ihm gespeichert sind, werden diese Informationen in History.state deserialisiert; andernfalls ist state null.
12. Wenn sich der Wert von state geändert hat, wird das popstate-Ereignis an das Dokument gesendet.
13. Jede persistente Benutzerstatus wird wiederhergestellt, wenn der Browser dies wählt.
14. Wenn die originalen und neuen Einträge das gleiche Dokument teilten, aber verschiedene Fragmente in ihren URLs hatten, senden Sie das hashchange-Ereignis an das Fenster.

Wie Sie sehen können, ist das popstate-Ereignis fast das letzte, was im Prozess des Navigierens zwischen Seiten auf diese Weise getan wird.

Beispiele

Eine Seite unter http://example.com/example.html, die den folgenden Code ausführt, wird Protokolle wie angegeben erzeugen:

window.addEventListener("popstate", (event) => {
  console.log(
    `location: ${document.location}, state: ${JSON.stringify(event.state)}`,
  );
});
history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // Logs "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // Logs "location: http://example.com/example.html, state: null"
history.go(2); // Logs "location: http://example.com/example.html?page=3, state: {"page":3}"

Das gleiche Beispiel unter Verwendung der onpopstate-Ereignis-Handler-Eigenschaft:

window.onpopstate = (event) => {
  console.log(
    `location: ${document.location}, state: ${JSON.stringify(event.state)}`,
  );
};
history.pushState({ page: 1 }, "title 1", "?page=1");
history.pushState({ page: 2 }, "title 2", "?page=2");
history.replaceState({ page: 3 }, "title 3", "?page=3");
history.back(); // Logs "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // Logs "location: http://example.com/example.html, state: null"
history.go(2); // Logs "location: http://example.com/example.html?page=3, state: {"page":3}"

Beachten Sie, dass selbst wenn der ursprüngliche Verlaufseintrag (für http://example.com/example.html) kein Zustandsobjekt zugeordnet hat, ein popstate-Ereignis trotzdem gesendet wird, wenn wir diesen Eintrag nach dem zweiten Aufruf von history.back() aktivieren.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Manipulation des Browserverlaufs (die History API)
• Window: hashchange-Ereignis