PageSwapEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface PageSwapEvent extends Event

Beschreibung

PageSwapEvent ist das Ereignisobjekt, das Handler des pageswap-Ereignisses am window erhalten. Das Ereignis wird ausgelöst, wenn das aktuelle Dokument wegen einer Navigation gleich entladen oder ersetzt wird. Es kommt nach dem letzten gerenderten Frame der alten Seite und vor pagehide.

Gebraucht wird es vor allem für dokumentübergreifende View Transitions, also animierte Übergänge zwischen zwei echten Seitenaufrufen (Multi-Page-Apps). Im Handler kann die ausgehende Seite kurz vor dem Schnappschuss noch Dinge ändern, etwa view-transition-name gezielt an Elemente vergeben, die zum Navigationsziel passen, oder den Übergang ganz überspringen.

Zwei Eigenschaften zusätzlich zu Event:

activation (NavigationActivation | null): Informationen zur Navigation, nämlich entry (Ziel-Eintrag mit url), from (aktueller Eintrag) und navigationType ("push", "replace", "reload" oder "traverse"). Der Wert ist null bei ursprungsübergreifenden Navigationen, auch bei Weiterleitungen auf fremde Ursprünge.
viewTransition (ViewTransition | null): das laufende ausgehende View Transition. Der Wert ist null, wenn kein dokumentübergreifender Übergang aktiv ist, zum Beispiel weil CSS @view-transition { navigation: auto; } fehlt.

Das Gegenstück auf der neuen Seite ist PageRevealEvent (Ereignis pagereveal).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor `new PageSwapEvent(type, options)`: der Name des Ereignisses, normalerweise `"pageswap"`.
$options	object	{}	Nur beim Konstruktor. Nimmt zusätzlich zu den `EventInit`-Feldern (`bubbles`, `cancelable`, `composed`) diese Felder an: `activation` (`NavigationActivation \| null`, Standard `null`) und `viewTransition` (`ViewTransition \| null`, Standard `null`).

Rückgabewert

Typ

PageSwapEvent

Beschreibung

Beim Konstruktor eine neue PageSwapEvent-Instanz. Normalerweise erzeugt der Browser das Objekt selbst und übergibt es an den pageswap-Handler.

Beispiele

Navigationsziel beim Verlassen protokollieren

window.addEventListener('pageswap', (event) => {
  if (event.activation) {
    const { navigationType, entry, from } = event.activation;
    console.log(`${navigationType}: ${from.url} → ${entry.url}`);
  } else {
    console.log('Ursprungsübergreifende Navigation – keine Details verfügbar');
  }
  console.log('View Transition aktiv:', event.viewTransition !== null);
});

push: https://example.com/produkte → https://example.com/produkte/42 View Transition aktiv: true

Gezielter Übergang zur Detailseite (View Transition-Namen setzen)

/* CSS auf beiden Seiten nötig:
   @view-transition { navigation: auto; } */

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

  const targetUrl = new URL(event.activation.entry.url);
  const match = targetUrl.pathname.match(/^\/produkte\/(\d+)$/);
  if (!match) return;

  // Nur das angeklickte Produktbild wird animiert
  const img = document.querySelector(`[data-produkt-id="${match[1]}"] img`);
  if (img) img.style.viewTransitionName = 'produktbild';

  // Aufräumen, falls die Seite aus dem bfcache zurückkehrt
  await event.viewTransition.finished;
  if (img) img.style.viewTransitionName = '';
});

Übergang bei Reload überspringen

window.addEventListener('pageswap', (event) => {
  if (event.viewTransition && event.activation?.navigationType === 'reload') {
    event.viewTransition.skipTransition();
  }
});

Ereignis manuell erzeugen (z. B. für Tests)

const evt = new PageSwapEvent('pageswap', { activation: null, viewTransition: null });
console.log(evt instanceof Event, evt.type, evt.activation, evt.viewTransition);

true pageswap null null

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 124 und Safari ab 18.2. Firefox unterstützt das Ereignis noch nicht. Vorher per 'PageSwapEvent' in window prüfen und den Code als progressive Verbesserung schreiben.
event.viewTransition ist nur gesetzt, wenn beide Seiten per CSS @view-transition { navigation: auto; } zustimmen und die Navigation im selben Ursprung bleibt. Andernfalls ist der Wert null.
event.activation ist bei ursprungsübergreifenden Navigationen und Weiterleitungen immer null. Das soll verhindern, dass Informationen an fremde Ursprünge gelangen.
Den Handler schon früh registrieren (Skript im <head> oder frühes Modul) und darin nur synchrone, schnelle Arbeit erledigen. Der Browser wartet nicht auf Promises, und langsamer Code verzögert die Navigation.
Gesetzte view-transition-name-Werte nach viewTransition.finished wieder entfernen. Sonst bleiben sie erhalten, wenn die Seite aus dem Back/Forward-Cache wiederhergestellt wird, und kollidieren beim nächsten Übergang, denn doppelte Namen brechen den Übergang ab.
Für reine Aufräum- oder Analyse-Aufgaben beim Verlassen der Seite sind pagehide und visibilitychange weiterhin die verlässlicheren Ereignisse.

Siehe auch

GamepadEvent PageRevealEvent SnapEvent GestureEvent MessageEvent