Window: popstate-Ereignis

Syntax

Verwenden Sie den Ereignisnamen in addEventListener():

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

Alternativ können Sie ihn der Event-Handler-Eigenschaft der Schnittstelle zuweisen:

onpopstate = (event) => { }

Ereignistyp

Ein PopStateEvent. Erbt von Event.

Event-Handler-Aliasse

Neben der Window-Schnittstelle ist die Event-Handler-Eigenschaft onpopstate auch auf den folgenden Elementen verfügbar:

• HTMLBodyElement
• HTMLFrameSetElement
• SVGSVGElement

Der Verlaufsstapel

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

Mit diesen Methoden und den zugehörigen Ereignissen lassen sich Daten zum Verlaufsstapel hinzufügen. Diese Daten können verwendet werden, um eine dynamisch erzeugte Seite wiederherzustellen oder den Zustand des angezeigten Inhalts auf andere Weise zu ändern, ohne das aktuelle Document zu verlassen.

Beachten Sie, dass der bloße Aufruf von history.pushState() oder history.replaceState() kein popstate-Ereignis auslöst. Das popstate-Ereignis wird durch eine Browseraktion ausgelöst, etwa durch einen Klick auf die Zurück- oder Vorwärts-Schaltfläche (oder durch einen Aufruf von history.back() oder history.forward() in JavaScript).

Wann popstate ausgelöst wird

Zunächst ist wichtig zu wissen, dass Browser das popstate-Ereignis möglicherweise überhaupt nicht auslösen, solange keine Interaktion mit der Seite stattgefunden hat. Damit sollen unerwünschte Pop-ups verhindert werden.

Dieser Abschnitt beschreibt die Schritte, die Browser in den Fällen ausführen, in denen sie das popstate-Ereignis potenziell auslösen können (also wenn eine Interaktion mit der Seite stattgefunden hat).

Bei einer Navigation – sei es durch Betätigen der Zurück-Schaltfläche des Browsers oder auf andere Weise – tritt das popstate-Ereignis gegen Ende des Navigationsvorgangs zum neuen Ziel auf. Es geschieht, nachdem das neue Ziel (falls nötig) geladen, angezeigt und sichtbar gemacht wurde und nachdem das pageshow-Ereignis gesendet wurde, aber bevor gespeicherte Informationen zum Benutzerzustand wiederhergestellt und das hashchange-Ereignis gesendet werden.

Um besser zu verstehen, wann das popstate-Ereignis ausgelöst wird, betrachten Sie die folgende vereinfachte Abfolge von Ereignissen. Sie tritt auf, wenn sich der aktuelle Verlaufseintrag ändert, weil der Benutzer auf der Website navigiert oder der Verlauf programmgesteuert durchlaufen wird. Bei diesem Übergang wird ein Verlaufseintrag aktuell, den wir new-entry nennen. Den bisherigen Eintrag im Sitzungsverlauf der aktuellen Seite nennen wir current-entry.

1. Falls new-entry noch kein vorhandenes Document enthält, wird der Inhalt abgerufen und sein Document erstellt, bevor der Vorgang fortgesetzt wird. Dadurch werden später Ereignisse wie DOMContentLoaded und load an das Window gesendet, das das Dokument enthält. Die folgenden Schritte werden unterdessen weiter ausgeführt.
2. Falls der Titel von current-entry nicht mit einer der History-API-Methoden (pushState() oder replaceState()) festgelegt wurde, wird der Titel des Eintrags auf die Zeichenfolge gesetzt, die sein Attribut document.title zurückgibt.
3. Falls der Browser vor dem Verlassen von current-entry Zustandsinformationen mit diesem Eintrag speichern möchte, tut er dies nun. Der Eintrag verfügt dann über einen „gespeicherten Benutzerzustand“. Zu den Informationen, die der Browser dem Eintrag im Sitzungsverlauf hinzufügen kann, gehören beispielsweise die Scrollposition des Dokuments, die Werte von Formulareingaben und ähnliche Daten.
4. Falls new-entry ein anderes Document-Objekt als current-entry hat, wird der Browserkontext so aktualisiert, dass seine document-Eigenschaft auf das Dokument verweist, auf das sich new-entry bezieht. Außerdem wird der Name des Kontexts an den Kontextnamen des nun aktuellen Dokuments angepasst.
5. Jedes Formularsteuerelement im Document von new-entry, bei dem für autocomplete der Autofill-Feldname off festgelegt ist, wird zurückgesetzt. Weitere Informationen zu Autofill-Feldnamen und zur Funktionsweise von autocomplete finden Sie unter Das HTML-Attribut autocomplete.
6. Falls das Dokument von new-entry bereits vollständig geladen und bereit ist – sein readyState also complete ist – und das Dokument noch nicht sichtbar ist, wird es sichtbar gemacht. Anschließend wird das pageshow-Ereignis am Dokument ausgelöst, wobei das Attribut persisted des PageTransitionEvent auf true gesetzt ist.
7. Die URL des Dokuments wird auf die URL von new-entry gesetzt.
8. Falls der Verlauf mit aktivierter Ersetzung durchlaufen wird, wird der Eintrag unmittelbar vor dem Zieleintrag aus dem Verlaufsstapel entfernt. Dabei wird der Parameter delta von Methoden wie go() berücksichtigt.
9. Falls new-entry keinen gespeicherten Benutzerzustand hat und das Fragment seiner URL nicht null ist, wird das Dokument zu diesem Fragment gescrollt.
10. Anschließend wird current-entry auf new-entry gesetzt. Der Zieleintrag gilt nun als aktuell.
11. Falls mit new-entry serialisierte Zustandsinformationen gespeichert wurden, werden diese in History.state deserialisiert. Andernfalls ist state gleich null.
12. Falls sich der Wert von state geändert hat, wird das popstate-Ereignis an das Dokument gesendet.
13. Gespeicherter Benutzerzustand wird wiederhergestellt, sofern der Browser dies vorsieht.
14. Falls sich der ursprüngliche und der neue Eintrag auf dasselbe Dokument beziehen, ihre URLs aber unterschiedliche Fragmente enthalten, wird das hashchange-Ereignis an das Fenster gesendet.

Wie Sie sehen, gehört das popstate-Ereignis zu den letzten Schritten bei dieser Art der Navigation zwischen Seiten.

Beispiele

Eine Seite unter http://example.com/example.html, die den folgenden Code ausführt, erzeugt die angegebenen Protokollausgaben:

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 Event-Handler-Eigenschaft onpopstate (beachten Sie jedoch, dass dadurch gegebenenfalls andere über onpopstate hinzugefügte Event-Listener ersetzt werden):

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 dann ein popstate-Ereignis ausgelöst wird, wenn wir nach dem zweiten Aufruf von history.back() den ursprünglichen Verlaufseintrag (für http://example.com/example.html) aktivieren, obwohl diesem kein Zustandsobjekt zugeordnet ist.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Den Browserverlauf bearbeiten (die History API)
• Window: hashchange-Ereignis