Window: popstate-Ereignis

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

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

Ein PopStateEvent. Erbt von Event.

PopStateEvent.state Schreibgeschützt

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

Zusätzlich zur Window-Schnittstelle ist die Ereignishandler-Eigenschaft onpopstate auch für die folgenden Elemente verfügbar:

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

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

Diese Methoden und deren entsprechende Ereignisse können verwendet werden, um Daten zum Verlauf hinzuzufügen, die verwendet werden können, um eine dynamisch generierte Seite zu rekonstruieren oder um den Zustand der präsentierten Inhalte zu ändern, während man im selben Document bleibt.

Beachten Sie, dass das bloße Aufrufen von history.pushState() oder history.replaceState() kein popstate-Ereignis auslöst. Das popstate-Ereignis wird durch eine Browser-Aktion wie einen Klick auf die Zurück- oder Vorwärtstaste (oder durch das Aufrufen von history.back() oder history.forward() in JavaScript) ausgelöst.

Browser behandeln das popstate-Ereignis beim Laden der Seite unterschiedlich. Chrome (vor Version 34) und Safari senden immer ein popstate-Ereignis beim Laden der Seite, aber Firefox tut dies nicht.

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 möglicherweise das popstate-Ereignis auslösen (das heißt, in den Fällen, in denen mit der Seite interagiert wurde).

Wenn eine Navigation erfolgt — entweder weil der Benutzer die Zurück-Taste des Browsers aktiviert oder auf andere Weise —, dann ist das popstate-Ereignis gegen Ende des Prozesses, um zur neuen Position zu navigieren. Es passiert, nachdem die neue Position geladen (falls erforderlich), angezeigt, sichtbar gemacht usw. wurde — nachdem das pageshow-Ereignis gesendet wurde, aber bevor die gespeicherten Benutzerstatusinformationen wiederhergestellt 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 der Navigation des Benutzers auf der Website oder der programmgesteuerten Durchquerung der Historie ändert. Hier ändert die Übergangsbewegung den aktuellen Verlaufseintrag zu einem, den wir als new-entry bezeichnen. Der Sitzungshistorien-Eintrag der aktuellen Seite wird als current-entry bezeichnet.

1. Wenn new-entry derzeit kein vorhandenes Document enthält, holen Sie den Inhalt und erstellen Sie dessen Document, bevor Sie fortfahren. Dadurch werden schließlich Ereignisse wie DOMContentLoaded und load an das Window gesendet, das das Dokument enthält, aber die folgenden Schritte werden gleichzeitig weiter 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 Eintragstitel auf die Zeichenkette, die von seinem document.title-Attribut zurückgegeben wird.
3. Wenn der Browser Statusinformationen speichern möchte, die mit current-entry verknüpft sind, bevor er weg navigiert, tut er dies. Der Eintrag gilt jetzt als "persistierter Benutzerstatus". Diese Informationen, die der Browser dem Sitzungsverlaufseintrag hinzufügen könnte, können zum Beispiel die Scrollposition des Dokuments, die Werte von Formulareingaben und andere solche Daten umfassen.
4. Wenn new-entry ein anderes Document-Objekt als current-entry hat, wird der Browsingkontext aktualisiert, sodass seine document-Eigenschaft auf das Dokument verweist, das von new-entry referenziert wird, und der Kontextname wird aktualisiert, um mit dem Kontextnamen des nun aktuellen Dokuments übereinzustimmen.
5. Jedes Formularelement innerhalb von new-entry's Document, das autocomplete mit seinem Autofill-Feldnamen auf off konfiguriert hat, wird zurückgesetzt. Siehe Das HTML autocomplete-Attribut, um mehr über die autocomplete-Feldnamen und die Funktionsweise von Autocomplete zu erfahren.
6. Wenn das Dokument von new-entry bereits vollständig geladen und bereit ist — das heißt, sein readyState ist complete — und das Dokument nicht bereits sichtbar ist, wird es sichtbar gemacht und das pageshow-Ereignis wird an das Dokument mit dem PageTransitionEvent's persisted-Attribut auf true ausgelöst.
7. Die URL des Dokuments wird auf die von new-entry gesetzt.
8. Wenn die Historien-Durchquerung mit aktivierter Ersetzung durchgeführt wird, wird der Eintrag, der unmittelbar vor dem Zieleintrag liegt (unter Berücksichtigung des delta-Parameters bei Methoden wie go()), aus dem Historienstapel entfernt.
9. Wenn new-entry keinen persistierten 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 Zieleintrag wird nun als aktuell betrachtet.
11. Wenn new-entry serielle Statusinformationen gespeichert hat, 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. Jeglicher persistierte Benutzerstatus wird wiederhergestellt, wenn sich der Browser dafür entscheidet.
14. Wenn die ursprünglichen und neuen Einträge dasselbe Dokument geteilt haben, aber unterschiedliche 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 beim Navigieren auf diese Weise getan wird.

Eine Seite unter http://example.com/example.html, die den folgenden Code ausführt, wird die angegebenen Protokolle 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}"

Dasselbe Beispiel mit der onpopstate-Ereignishandler-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 auch wenn der ursprüngliche Verlaufseintrag (für http://example.com/example.html) kein Zustandsobjekt zugeordnet hat, ein popstate-Ereignis immer noch ausgelöst wird, wenn wir diesen Eintrag nach dem zweiten Aufruf von history.back() aktivieren.

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