Document.activeViewTransition — Eigenschaft · JavaScript-Referenz

Signatur

get Document.activeViewTransition

Beschreibung

document.activeViewTransition gibt das ViewTransition-Objekt des Ansichtsübergangs zurück, der gerade auf dem Dokument läuft. Das gilt sowohl für Übergänge innerhalb desselben Dokuments, die mit document.startViewTransition() gestartet wurden, als auch für Übergänge zwischen Dokumenten (per CSS-Regel @view-transition { navigation: auto; }). Läuft kein Übergang, ist der Wert null.

Nützlich ist die Eigenschaft vor allem, wenn du den Rückgabewert von startViewTransition() nicht an alle Stellen weiterreichen kannst oder willst – etwa in Komponenten, Bibliotheken oder globalen Event-Handlern. Damit kannst du jederzeit prüfen, ob gerade eine Animation läuft, auf ihr Ende warten (finished), sie abbrechen (skipTransition()) oder ihre Typen (types) ändern.

Bei Übergängen zwischen Dokumenten stehen dir zwar auch event.viewTransition in den Events pageswap und pagereveal zur Verfügung. activeViewTransition bietet aber einen einheitlichen Zugriff von jeder Stelle im Code aus, solange der Übergang läuft.

Rückgabewert

Typ

ViewTransition | null

Beschreibung

Den aktuell aktiven ViewTransition oder null, wenn gerade kein Ansichtsübergang läuft.

Beispiele

Prüfen, ob gerade ein Übergang läuft

const updateView = (renderFn) => {
  // Keine API-Unterstützung: einfach direkt rendern
  if (!document.startViewTransition) {
    renderFn();
    return;
  }
  // Laufenden Übergang abbrechen, bevor ein neuer startet
  document.activeViewTransition?.skipTransition();
  document.startViewTransition(renderFn);
};

updateView(() => {
  document.querySelector('#content').textContent = 'Neue Ansicht';
});
console.log(document.activeViewTransition !== null);

true

Auf das Ende eines Übergangs warten, ohne die Referenz weiterzureichen

const waitForTransitionEnd = async () => {
  const transition = document.activeViewTransition;
  if (!transition) return;
  try {
    await transition.finished;
  } catch {
    // finished wird nicht verworfen, aber sicherheitshalber abfangen
  }
};

// z. B. in einer Komponente, die Fokus erst nach der Animation setzen soll
const focusSearch = async () => {
  await waitForTransitionEnd();
  document.querySelector('#search')?.focus();
  console.log('Fokus gesetzt');
};

focusSearch();

Fokus gesetzt

Übergangstyp bei einer Navigation zwischen Dokumenten ergänzen

// Erfordert im CSS: @view-transition { navigation: auto; }
window.addEventListener('pagereveal', () => {
  const transition = document.activeViewTransition;
  if (!transition) return;

  const from = navigation.activation?.from?.url ?? '';
  if (from.includes('/produkte/')) {
    // CSS kann mit :active-view-transition-type(zurueck) reagieren
    transition.types.add('zurueck');
  }
  console.log([...transition.types]);
});

["zurueck"]

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist sehr neu (Chromium ab Version 142) und noch nicht Baseline. Prüfe per 'activeViewTransition' in document oder verwende optionale Verkettung (?.). Ohne Unterstützung ist der Wert undefined, nicht null.
Der Wert ist nur während des Übergangs gesetzt. Nach dem Auflösen von finished oder nach skipTransition() ist er wieder null. Speichere die Referenz also in einer Variablen, wenn du sie über mehrere await-Schritte brauchst.
Pro Dokument kann immer nur ein Übergang aktiv sein. Ein neuer Aufruf von startViewTransition() bricht den laufenden ab. Dessen ready-Promise wird dann mit einem AbortError verworfen.
Die Eigenschaft ist schreibgeschützt. Zuweisungen werden ignoriert und werfen im Strict Mode einen Fehler.
Bei Übergängen zwischen Dokumenten müssen beide Seiten denselben Ursprung haben und sich per @view-transition dafür anmelden.

Siehe auch

Document.startViewTransition() ViewTransition ViewTransition.skipTransition() ViewTransition.finished ViewTransition.types