PageRevealEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface PageRevealEvent extends Event

Beschreibung

PageRevealEvent ist das Ereignisobjekt, das Handler des pagereveal-Ereignisses erhalten. Das Ereignis wird auf window ausgelöst, sobald ein Dokument zum ersten Mal gerendert wird. Das passiert beim normalen Laden über das Netzwerk, beim Wiederherstellen aus dem Back/Forward-Cache (bfcache) und beim Aktivieren einer vorab gerenderten Seite (Prerendering).

Die wichtigste Eigenschaft ist viewTransition. Sie enthält das ViewTransition-Objekt einer aktiven dokumentübergreifenden View Transition, die per CSS mit @view-transition { navigation: auto; } aktiviert wurde. Gibt es keine solche Transition, ist der Wert null. Damit kann die Zielseite einer Navigation die Animation anpassen, etwa per view-transition-name dynamisch Elemente markieren, per types Transition-Typen setzen oder die Transition mit skipTransition() abbrechen.

Das Gegenstück auf der Ausgangsseite ist das pageswap-Ereignis (PageSwapEvent). Mit beiden zusammen lässt sich eine Transition über beide Dokumente hinweg steuern. Welche Navigation stattfindet, erfährt man auf der Zielseite über navigation.activation (Navigation API).

Du kannst entweder window.addEventListener("pagereveal", handler) oder die Eigenschaft window.onpagereveal verwenden. Da das Ereignis vor dem ersten Rendern ausgelöst wird, muss der Handler sehr früh registriert werden, am besten in einem blockierenden (nicht async/defer) Skript im <head>.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor `new PageRevealEvent(type, options)`: Name des Ereignisses, normalerweise `"pagereveal"`.
$options	object	{}	Nur beim Konstruktor: Optionen wie bei `Event` (`bubbles`, `cancelable`, `composed`) und zusätzlich `viewTransition` (`ViewTransition \| null`, Standard `null`).
$viewTransition	ViewTransition \| null	null	Schreibgeschützte Instanzeigenschaft: die aktive dokumentübergreifende View Transition oder `null`, wenn keine läuft.

Rückgabewert

Typ

PageRevealEvent

Beschreibung

Der Konstruktor liefert ein neues PageRevealEvent. In der Praxis erzeugt der Browser das Objekt selbst und übergibt es an pagereveal-Handler.

Beispiele

Grundlegender Handler: prüfen, ob eine View Transition läuft

// Im <head> als blockierendes Skript einbinden
window.addEventListener("pagereveal", (event) => {
  if (event.viewTransition) {
    console.log("Dokumentübergreifende View Transition aktiv");
    event.viewTransition.finished.then(() => {
      console.log("Transition abgeschlossen");
    });
  } else {
    console.log("Keine View Transition");
  }
});

Dokumentübergreifende View Transition aktiv Transition abgeschlossen

Transition je nach Herkunft der Navigation überspringen

/* CSS: @view-transition { navigation: auto; } */
window.addEventListener("pagereveal", (event) => {
  if (!event.viewTransition) return;

  const fromUrl = navigation.activation?.from?.url;
  if (!fromUrl) return;

  // Keine Animation, wenn wir von der Login-Seite kommen
  if (new URL(fromUrl).pathname === "/login") {
    event.viewTransition.skipTransition();
  }
});

Dynamische view-transition-name für eine Detailseite

window.onpagereveal = async (event) => {
  if (!event.viewTransition) return;

  const bild = document.querySelector(".produkt-bild");
  if (!bild) return;

  // Element nur für diese Transition benennen
  bild.style.viewTransitionName = "produkt";
  event.viewTransition.types.add("zur-detailseite");

  // Nach dem Erfassen der Snapshots wieder entfernen
  await event.viewTransition.ready;
  bild.style.viewTransitionName = "none";
};

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

const ev = new PageRevealEvent("pagereveal", { viewTransition: null });
console.log(ev.type, ev.viewTransition);

pagereveal null

// Wichtig · Fallstricke

Frühe Registrierung: pagereveal wird vor dem ersten Rendern ausgelöst. Handler in Skripten mit defer, async oder type="module" sowie am Ende des <body> kommen oft zu spät und verpassen das Ereignis.
viewTransition ist nur gesetzt, wenn beide Dokumente per @view-transition { navigation: auto; } zustimmen, die Navigation innerhalb desselben Ursprungs (same-origin) bleibt und nicht per Neuladen ausgelöst wurde. Sonst ist der Wert null. Prüfe den Wert deshalb immer, bevor du ihn nutzt.
Das Ereignis wird auch bei Wiederherstellung aus dem bfcache ausgelöst, anders als DOMContentLoaded oder load. Einmalige Initialisierung solltest du deshalb nicht in diesen Handler legen.
Dynamisch gesetzte view-transition-name-Werte nach viewTransition.ready wieder entfernen, sonst stören doppelte Namen spätere Transitions.
Kompatibilität: Unterstützt ab Chromium 123 und Safari 18.2. In Firefox noch nicht vollständig verfügbar. Nutze Feature-Erkennung per "onpagereveal" in window. Ohne Unterstützung wird die Seite einfach ohne Animation angezeigt (progressive Verbesserung).

Siehe auch

Navigation.activation PageSwapEvent GamepadEvent InterestEvent ProgressEvent