PageSwapEvent.viewTransition — Eigenschaft · JavaScript-Referenz

Signatur

PageSwapEvent.viewTransition

Beschreibung

Die Eigenschaft viewTransition des Interfaces PageSwapEvent enthält ein ViewTransition-Objekt. Es steht für den dokumentübergreifenden Ansichtsübergang (Cross-Document View Transition), der gerade für eine Navigation vorbereitet wird. Hinweis: In der MDN-Kurzbeschreibung steht fälschlich PageRevealEvent. Beide Events haben eine gleichnamige Eigenschaft, hier geht es aber um die Seite, die verlassen wird.

Das Ereignis pageswap wird auf window ausgelöst, kurz bevor das alte Dokument durch das neue ersetzt wird. Das passiert erst nach der letzten Weiterleitung, direkt bevor der Zustand der alten Seite für den Übergang festgehalten wird. Damit ist das der letzte Moment, in dem die ausgehende Seite den Übergang anpassen kann. Typische Aufgaben:

Je nach Navigationsziel view-transition-name auf passende Elemente setzen, zum Beispiel auf das angeklickte Vorschaubild.
Über viewTransition.types Übergangstypen setzen, etwa „vorwärts“ oder „rückwärts“.
Den Übergang mit viewTransition.skipTransition() abbrechen, wenn er für bestimmte Ziele nicht passt.
Über viewTransition.finished aufräumen, wenn die Seite aus dem Back/Forward-Cache zurückkommt.

Der Wert ist null, wenn kein Übergang stattfindet. Das ist der Fall, wenn die Seite dokumentübergreifende Übergänge nicht per CSS aktiviert hat (@view-transition { navigation: auto; }), die Navigation zu einer anderen Herkunft (Origin) führt oder der Browser die Funktion nicht unterstützt. Weitere Infos zur Navigation, etwa die Ziel-URL, liefert die Schwester-Eigenschaft PageSwapEvent.activation.

Rückgabewert

Typ

ViewTransition | null

Beschreibung

Das ViewTransition-Objekt des geplanten dokumentübergreifenden Übergangs oder null, wenn für diese Navigation kein Übergang stattfindet.

Beispiele

Prüfen, ob ein Übergang stattfindet

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

window.addEventListener('pageswap', (event) => {
  if (event.viewTransition) {
    console.log('Dokumentübergreifender Übergang wird vorbereitet');
  } else {
    console.log('Kein Übergang (nicht aktiviert oder andere Herkunft)');
  }
});

Dokumentübergreifender Übergang wird vorbereitet

Angeklicktes Vorschaubild gezielt animieren und danach aufräumen

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

  const ziel = new URL(activation.entry.url);
  // Beispiel: /produkte/42 -> Vorschaubild mit data-id="42"
  const id = ziel.pathname.split('/').pop();
  const bild = document.querySelector(`.vorschau[data-id="${id}"] img`);
  if (!bild) return;

  // Muss synchron im Handler passieren, bevor der Zustand festgehalten wird
  bild.style.viewTransitionName = 'produkt-bild';

  // Aufräumen, falls die Seite aus dem bfcache wiederhergestellt wird
  await viewTransition.finished;
  bild.style.viewTransitionName = '';
});

Übergang je nach Ziel abbrechen oder mit Typ versehen

window.addEventListener('pageswap', (event) => {
  const vt = event.viewTransition;
  if (!vt) return;

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

  // Zum Abmelden keine Animation
  if (ziel.pathname === '/logout') {
    vt.skipTransition();
    return;
  }

  // Richtung als Typ setzen, im CSS über :active-view-transition-type() nutzbar
  if (event.activation.navigationType === 'traverse') {
    vt.types?.add('zurueck');
  } else {
    vt.types?.add('vorwaerts');
  }
});

// Wichtig · Fallstricke

Häufig null: Ein Übergang findet nur statt, wenn beide Dokumente @view-transition { navigation: auto; } gesetzt haben und dieselbe Herkunft haben. Bei Navigationen zu einer anderen Herkunft sind viewTransition und activation null. Deshalb vor dem Zugriff immer prüfen.
Nur synchron ändern: Änderungen am DOM und an view-transition-name müssen direkt im Handler passieren. Nach einem await ist der Zustand der alten Seite schon festgehalten.
Eindeutige Namen: Jeder view-transition-name darf zum Zeitpunkt des Festhaltens nur einmal vorkommen. Sonst wird der Übergang übersprungen und finished wird trotzdem erfüllt.
Back/Forward-Cache: Kehrt die Seite aus dem bfcache zurück, sind die gesetzten Stile noch da. Deshalb nach viewTransition.finished aufräumen.
Handler früh registrieren: Den Listener früh anmelden. Das Gegenstück auf der neuen Seite ist pagereveal; dessen Listener muss vor dem ersten Rendern registriert sein, zum Beispiel in einem blockierenden Skript im <head>.
Kompatibilität: Chromium 124+ und Safari 18.2+. Firefox unterstützt dokumentübergreifende Übergänge noch nicht. viewTransition.types gibt es erst ab Chromium 125, deshalb optional prüfen (?.). Ohne Unterstützung gibt es einfach keinen Übergang, die Seite funktioniert trotzdem (progressive Verbesserung).

Siehe auch

PageSwapEvent.activation PageRevealEvent.viewTransition Element.activeViewTransition Document.activeViewTransition NavigateEvent.destination