ViewTransition.finished — Eigenschaft · JavaScript-Referenz

Signatur

ViewTransition.finished

Beschreibung

Die schreibgeschützte Eigenschaft finished einer ViewTransition liefert ein Promise<undefined>. Es wird erfüllt, sobald alle Übergangsanimationen abgeschlossen sind, der Pseudo-Element-Baum (::view-transition) entfernt wurde und die neue Ansicht wieder normal sichtbar und für Eingaben bereit ist.

Das ist der richtige Zeitpunkt für Aufräumarbeiten: temporäre Klassen entfernen, view-transition-name-Werte zurücksetzen, den Fokus setzen, Analyse-Ereignisse senden oder die nächste Transition freigeben. Im Unterschied zu ready (Pseudo-Elemente sind erzeugt, die Animation beginnt gleich) und updateCallbackDone (das DOM-Update ist erledigt) markiert finished das tatsächliche Ende des ganzen Vorgangs.

Wichtig: finished wird nur dann abgelehnt, wenn der Update-Callback selbst ein abgelehntes Promise zurückgibt oder eine Ausnahme wirft. Wird die Animation übersprungen, z. B. über skipTransition(), durch einen doppelten view-transition-name oder weil eine neue Transition gestartet wurde, wird finished trotzdem erfüllt, solange das DOM-Update erfolgreich war. Der Grund: Der Zustand der Seite hat sich ja wie gewünscht geändert.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Transition beendet ist. Es wird mit dem Fehler des Update-Callbacks abgelehnt, falls dieser fehlschlägt.

Beispiele

Aufräumen nach dem Übergang

const toggleTheme = () => {
  // Fallback für Browser ohne View Transitions
  if (!document.startViewTransition) {
    document.documentElement.classList.toggle('dark');
    return;
  }

  document.documentElement.classList.add('theme-transition');

  const transition = document.startViewTransition(() => {
    document.documentElement.classList.toggle('dark');
  });

  transition.finished.then(() => {
    document.documentElement.classList.remove('theme-transition');
    console.log('Übergang abgeschlossen');
  });
};

document.querySelector('#theme-btn').addEventListener('click', toggleTheme);

Übergang abgeschlossen

Temporären view-transition-name zurücksetzen (async/await)

const openDetail = async (thumbnail, renderDetail) => {
  // Nur dieses eine Bild bekommt für die Dauer des Übergangs einen Namen
  thumbnail.style.viewTransitionName = 'hero-image';

  const transition = document.startViewTransition(async () => {
    thumbnail.style.viewTransitionName = '';
    await renderDetail(); // setzt im neuen DOM ebenfalls 'hero-image'
  });

  try {
    await transition.finished;
    document.querySelector('#detail h1')?.focus();
  } catch (err) {
    console.error('DOM-Update fehlgeschlagen:', err);
  }
};

Reihenfolge der drei Promises beobachten

const transition = document.startViewTransition(() => {
  document.body.classList.toggle('alt-layout');
});

transition.updateCallbackDone.then(() => console.log('1. DOM aktualisiert'));
transition.ready.then(() => console.log('2. Animation startet'));
transition.finished.then(() => console.log('3. Übergang beendet'));

1. DOM aktualisiert 2. Animation startet 3. Übergang beendet

finished wird auch bei skipTransition() erfüllt

const transition = document.startViewTransition(() => {
  document.querySelector('#counter').textContent = '42';
});

transition.skipTransition();

transition.ready.catch(() => console.log('ready abgelehnt (Animation übersprungen)'));
transition.finished.then(() => console.log('finished trotzdem erfüllt'));

ready abgelehnt (Animation übersprungen) finished trotzdem erfüllt

// Wichtig · Fallstricke

Ablehnung nur bei Callback-Fehlern: Wenn finished erfüllt wird, heißt das nicht, dass eine Animation zu sehen war. Ob übersprungen wurde, erkennt man an einer Ablehnung von ready.
Unbehandelte Ablehnungen: Wirft der Update-Callback eine Ausnahme, werden updateCallbackDone, ready und finished alle abgelehnt. Wer nur finished abwartet, sollte die anderen Promises ebenfalls mit catch abfangen, sonst erscheinen Warnungen zu unhandled rejection.
Neue Transition bricht die alte ab: Startet während einer laufenden Transition ein weiteres startViewTransition(), wird die alte übersprungen, ihr finished aber trotzdem erfüllt. Gemeinsam genutzte Aufräumlogik sollte sich deshalb nicht in die Quere kommen.
Kompatibilität: Same-Document View Transitions gibt es in Chromium ab Version 111, in Safari ab 18 und in Firefox ab 144. Prüfen Sie die Unterstützung vor der Nutzung mit if (document.startViewTransition). Bei dokumentübergreifenden Transitions erhält man das ViewTransition-Objekt über die Ereignisse pageswap und pagereveal (event.viewTransition).
Wenn Nutzer prefers-reduced-motion gesetzt haben, sollten Sie die Animationen per CSS abschalten. finished wird dann fast sofort erfüllt.

Siehe auch

Promise CSSViewTransitionRule.navigation ViewTransition.types ViewTransition.ready ViewTransition.transitionRoot