new PageSwapEvent() — Methode · JavaScript-Referenz

Signatur

new PageSwapEvent(type, options)

Beschreibung

Der Konstruktor PageSwapEvent() erzeugt eine neue Instanz von PageSwapEvent. Normalerweise legt der Browser dieses Ereignis selbst an und löst es als pageswap am window aus. Das passiert, kurz bevor das aktuelle Dokument bei einer Navigation innerhalb desselben Ursprungs (same-origin) ersetzt wird. Das Ereignis gehört zum Konzept der dokumentübergreifenden View Transitions, also Übergängen zwischen verschiedenen Dokumenten (@view-transition { navigation: auto; }).

Das Ereignis hat zwei eigene Eigenschaften: viewTransition und activation. Über viewTransition erreicht man das laufende ViewTransition-Objekt, etwa um es mit skipTransition() abzubrechen oder um vor dem Schnappschuss noch view-transition-name-Werte zu setzen. activation ist eine NavigationActivation. Sie enthält Informationen zur Navigation, z. B. die Ziel-URL über activation.entry.url und die Art der Navigation über navigationType.

Den Konstruktor selbst braucht man vor allem, um das Ereignis synthetisch zu erzeugen: in Unit-Tests, zum Simulieren von Übergangslogik oder für eigene Event-Pipelines. Ein selbst ausgelöstes Ereignis startet keine echte View Transition. Es ruft nur die registrierten Listener auf.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Der Browser verwendet immer `"pageswap"`.
$options	object	{}	Optionales Objekt, das zusätzlich zu den Optionen von `Event()` (`bubbles`, `cancelable`, `composed`) diese Felder kennt: `activation` (`NavigationActivation \| null`, Standard `null`): Informationen zur auslösenden Navigation. `viewTransition` (`ViewTransition \| null`, Standard `null`): die zugehörige aktive View Transition.

Rückgabewert

Typ

PageSwapEvent

Beschreibung

Ein neues PageSwapEvent-Objekt mit den angegebenen Eigenschaften activation und viewTransition.

Beispiele

Synthetisches Ereignis erzeugen und auswerten

const evt = new PageSwapEvent('pageswap');

console.log(evt instanceof Event);
console.log(evt.type);
console.log(evt.viewTransition);
console.log(evt.activation);

true pageswap null null

Listener in einem Test manuell auslösen

const handler = (e) => {
  if (!e.viewTransition) {
    console.log('Keine View Transition aktiv – nichts zu tun');
    return;
  }
  console.log('Transition vorbereiten');
};

window.addEventListener('pageswap', handler);

// Browser-Verhalten simulieren
window.dispatchEvent(new PageSwapEvent('pageswap', { viewTransition: null }));

window.removeEventListener('pageswap', handler);

Keine View Transition aktiv – nichts zu tun

Praxis: echtes pageswap-Ereignis für eine dokumentübergreifende Transition nutzen

// CSS: @view-transition { navigation: auto; }
window.addEventListener('pageswap', async (e) => {
  if (!e.viewTransition || !e.activation) return;

  const targetUrl = new URL(e.activation.entry.url);

  // Nur beim Wechsel auf eine Produktdetailseite das Bild animieren
  if (targetUrl.pathname.startsWith('/produkt/')) {
    const img = document.querySelector(`[data-id="${targetUrl.pathname.split('/').pop()}"] img`);
    if (img) {
      img.style.viewTransitionName = 'produktbild';
      // Nach dem Schnappschuss wieder entfernen (wichtig für bfcache)
      await e.viewTransition.finished;
      img.style.viewTransitionName = '';
    }
  }

  // Bei Neuladen keine Animation
  if (e.activation.navigationType === 'reload') {
    e.viewTransition.skipTransition();
  }
});

// Wichtig · Fallstricke

Browser-Unterstützung: in Chromium ab Version 124 und in Safari ab 18.2 verfügbar. In Firefox fehlen dokumentübergreifende View Transitions bislang ganz oder teilweise. Vor der Nutzung mit 'PageSwapEvent' in window prüfen, ob die API vorhanden ist.
Ein mit dem Konstruktor erzeugtes und mit dispatchEvent() ausgelöstes Ereignis startet keine echte View Transition. Das Attribut isTrusted ist dabei false.
Einem synthetischen Ereignis kann man kaum echte Werte mitgeben: ViewTransition- und NavigationActivation-Objekte lassen sich nicht direkt konstruieren. Selbst erzeugte Ereignisse haben daher in der Regel null in beiden Eigenschaften.
activation ist null, wenn die Navigation einen anderen Ursprung hat (cross-origin) oder Weiterleitungen über andere Ursprünge führen. Das dient dem Datenschutz.
Listener für pageswap müssen schnell und synchron arbeiten. Der Schnappschuss der alten Seite entsteht direkt nach dem Ereignis. Spätere asynchrone Änderungen am DOM erscheinen darin nicht mehr.

Siehe auch

new CustomEvent() new GamepadEvent() new PageRevealEvent() new SnapEvent() new MessageEvent()