Window: pageswap — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("pageswap", handler)

Beschreibung

Das Ereignis pageswap wird am Window-Objekt des alten Dokuments ausgelöst, wenn der Nutzer zu einem anderen Dokument navigiert. Das Dokument wird danach entladen oder in den Back/Forward-Cache (bfcache) gelegt. Das Ereignis kommt nach dem letzten Einzelbild (Frame), das noch gezeichnet wird. Der Handler bekommt ein PageSwapEvent mit zwei Eigenschaften:

activation: ein NavigationActivation-Objekt mit dem Navigationstyp (navigationType) sowie dem aktuellen (from) und dem Ziel-Verlaufseintrag (entry). Bei Navigationen zu anderen Ursprüngen (Origins) ist der Wert null.
viewTransition: das ViewTransition-Objekt einer dokumentübergreifenden View Transition. Läuft keine Transition, ist der Wert null.

Hauptzweck ist die Anpassung von dokumentübergreifenden View Transitions, die per CSS mit @view-transition { navigation: auto; } aktiviert werden. Abhängig vom Navigationsziel kann man im alten Dokument im letzten Moment view-transition-name-Werte setzen, Typen zu viewTransition.types hinzufügen oder die Transition mit skipTransition() abbrechen.

Das Gegenstück ist pagereveal. Es wird im neuen Dokument vor dessen erstem Rendern ausgelöst. Zusammen erlauben beide Ereignisse die volle Kontrolle über Übergänge zwischen Seiten. Man kann pageswap außerdem nutzen, um Zustand kurz vor dem Verlassen der Seite zu sichern, zum Beispiel in sessionStorage.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"pageswap"`.
$handler Pflicht	(event: PageSwapEvent) => void		Callback, der ein `PageSwapEvent` mit den Eigenschaften `activation` (`NavigationActivation \| null`) und `viewTransition` (`ViewTransition \| null`) erhält.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignis selbst ist nicht abbrechbar (cancelable: false) und steigt nicht auf (bubbles: false).

Beispiele

Einfach: Navigationsdaten protokollieren

window.addEventListener("pageswap", (event) => {
  if (event.activation) {
    const { navigationType, entry } = event.activation;
    console.log(`Verlasse Seite per ${navigationType} nach ${entry.url}`);
  } else {
    console.log("Navigation zu fremdem Ursprung – keine Details verfügbar");
  }
  console.log("View Transition aktiv:", event.viewTransition !== null);
});

Verlasse Seite per push nach https://example.com/produkte/42 View Transition aktiv: true

Dokumentübergreifende View Transition gezielt anpassen

/* CSS in beiden Dokumenten: @view-transition { navigation: auto; } */

window.addEventListener("pageswap", async (event) => {
  const { viewTransition, activation } = event;
  if (!viewTransition || !activation) return;

  const ziel = new URL(activation.entry.url);

  // Nur beim Wechsel auf eine Profilseite das Avatarbild „mitwandern“ lassen
  if (ziel.pathname.startsWith("/profil/")) {
    const avatar = document.querySelector(`[data-user="${ziel.pathname.split("/")[2]}"] img`);
    if (avatar) {
      avatar.style.viewTransitionName = "avatar";
      viewTransition.types.add("zu-profil");

      // Nach dem Übergang aufräumen – wichtig, falls die Seite aus dem bfcache zurückkehrt
      await viewTransition.finished;
      avatar.style.viewTransitionName = "";
    }
  }

  // Beim Neuladen keine Animation
  if (activation.navigationType === "reload") {
    viewTransition.skipTransition();
  }
});

Zustand vor dem Seitenwechsel sichern

window.addEventListener("pageswap", () => {
  const scrollY = Math.round(window.scrollY);
  const filter = document.querySelector("#filter")?.value ?? "";
  sessionStorage.setItem("listenStatus", JSON.stringify({ scrollY, filter }));
});

// Auf der Folgeseite (oder bei Rückkehr) wieder einlesen
const status = JSON.parse(sessionStorage.getItem("listenStatus") ?? "null");
console.log(status);

{ scrollY: 840, filter: "schuhe" }

Alternative über die on-Property und Entfernen des Listeners

const onSwap = (event) => {
  console.log("pageswap", event.activation?.navigationType);
};

// Variante 1: on-Property
window.onpageswap = onSwap;
window.onpageswap = null; // wieder entfernen

// Variante 2: addEventListener / removeEventListener
window.addEventListener("pageswap", onSwap);
window.removeEventListener("pageswap", onSwap);

// Wichtig · Fallstricke

Browserunterstützung: Das Ereignis gibt es in Chromium-Browsern ab Version 124 und in Safari ab 18.2. Firefox unterstützt es derzeit nicht. Prüfe die Unterstützung mit "onpageswap" in window und nutze das Ereignis nur als progressive Verbesserung.
activation kann null sein: Führt die Navigation zu einem anderen Ursprung oder gibt es unterwegs eine Weiterleitung zu einem anderen Ursprung, stehen aus Datenschutzgründen keine Details zur Verfügung. Prüfe den Wert deshalb immer, bevor du darauf zugreifst.
viewTransition ist nur gesetzt, wenn beide Dokumente dokumentübergreifende View Transitions per @view-transition { navigation: auto; } aktiviert haben und die Navigation gleichen Ursprungs ist.
Aufräumen nicht vergessen: Die Seite kann in den bfcache wandern und später wiederhergestellt werden. Gesetzte view-transition-name-Werte sollten deshalb nach viewTransition.finished zurückgesetzt werden. Sonst gibt es bei der nächsten Transition doppelte Namen, und die Transition schlägt fehl.
Kein Ersatz für beforeunload: pageswap lässt sich nicht abbrechen und kann die Navigation nicht aufhalten. Im Handler sollten keine langen synchronen Arbeiten laufen, weil sie den Seitenwechsel verzögern.
Im Unterschied zu pagereveal muss der Listener nicht besonders früh registriert werden. Er muss nur bestehen, bevor die Navigation beginnt.

Siehe auch

Window: pageshow Window: pagehide Window: pagereveal Window: message Window: popstate Element: keyup HID: connect