PageSwapEvent.activation — Eigenschaft · JavaScript-Referenz

Signatur

PageSwapEvent.activation

Beschreibung

Die Eigenschaft activation des PageSwapEvent ist schreibgeschützt und enthält Informationen über die Navigation, die das aktuelle Dokument gerade verlässt. Das Ereignis pageswap wird am window ausgelöst, kurz bevor das Dokument bei einer dokumentübergreifenden Navigation entladen wird. Deshalb erfährt man hier, wohin die Navigation führt, obwohl das Dokument noch vorhanden ist.

Das zurückgegebene NavigationActivation-Objekt hat drei Eigenschaften:

entry: der NavigationHistoryEntry des Ziel-Dokuments, z. B. mit entry.url
from: der Verlaufseintrag des aktuellen Dokuments (das verlassen wird)
navigationType: "push", "replace", "reload" oder "traverse"

Am häufigsten braucht man die Eigenschaft für dokumentübergreifende View Transitions (@view-transition { navigation: auto; }). Abhängig von Ziel-URL oder Navigationstyp setzt man vor dem Schnappschuss des alten Zustands gezielt view-transition-name-Werte oder passt die Animation an. Außerdem kann man damit Analysedaten oder Zustände speichern, bevor die Seite verlassen wird.

Rückgabewert

Typ

NavigationActivation | null

Beschreibung

Ein NavigationActivation-Objekt mit entry, from und navigationType. Der Wert ist null, wenn die Navigation ursprungsübergreifend ist (auch wenn sie über ursprungsübergreifende Weiterleitungen führt).

Beispiele

Ziel und Navigationstyp protokollieren

window.addEventListener("pageswap", (event) => {
  const { activation } = event;
  if (!activation) {
    console.log("Ursprungsübergreifende Navigation – keine Details verfügbar");
    return;
  }
  console.log("Typ:", activation.navigationType);
  console.log("Von:", activation.from?.url);
  console.log("Nach:", activation.entry.url);
});

Typ: push Von: https://example.com/liste Nach: https://example.com/profil/anna

View Transition gezielt für Profilseiten vorbereiten

// CSS in beiden Seiten: @view-transition { navigation: auto; }
const isProfilePage = (url) => url.pathname.startsWith("/profil/");
const profileName = (url) => url.pathname.split("/")[2];

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

  const target = new URL(event.activation.entry.url);
  if (!isProfilePage(target)) return;

  const card = document.querySelector(`#${CSS.escape(profileName(target))}`);
  if (!card) return;

  // Namen nur für das angeklickte Element setzen
  card.querySelector("img").style.viewTransitionName = "avatar";
  card.querySelector("span").style.viewTransitionName = "name";

  // Nach dem Schnappschuss zurücksetzen (wichtig für bfcache-Rückkehr)
  await event.viewTransition.finished;
  card.querySelector("img").style.viewTransitionName = "none";
  card.querySelector("span").style.viewTransitionName = "none";
});

Übergang bei Neuladen und Zurück-Navigation überspringen

window.addEventListener("pageswap", (event) => {
  const type = event.activation?.navigationType;
  if (event.viewTransition && (type === "reload" || type === "traverse")) {
    event.viewTransition.skipTransition();
    console.log(`Übergang übersprungen (${type})`);
  }
});

Übergang übersprungen (traverse)

// Wichtig · Fallstricke

Immer auf null prüfen: Bei ursprungsübergreifenden Navigationen oder Weiterleitungen ist activation null. Ohne optionale Verkettung (?.) wirft der Zugriff auf activation.entry einen TypeError.
Im pageswap-Ereignis ist entry das Ziel und from das aktuelle Dokument. Bei pagereveal liest man die Daten dagegen über navigation.activation im neuen Dokument aus.
Den Listener früh registrieren und synchron arbeiten. Änderungen am DOM, die in den Schnappschuss eingehen sollen, müssen vor dem ersten await erfolgen.
Gesetzte view-transition-name-Werte wieder zurücksetzen. Sonst stören sie, wenn die Seite aus dem Back/Forward-Cache wiederhergestellt wird.
Kompatibilität: Chromium-Browser ab Version 124 und Safari ab 18.2. In Firefox fehlt die Unterstützung noch weitgehend. Vorher prüfen, ob die Funktion vorhanden ist, z. B. mit "PageSwapEvent" in window.

Siehe auch

PageSwapEvent.viewTransition Navigation.activation NavigateEvent.destination AnimationEvent.animation TransitionEvent.animation