ViewTransition.updateCallbackDone — Eigenschaft · JavaScript-Referenz

Signatur

ViewTransition.updateCallbackDone

Beschreibung

Die schreibgeschützte Eigenschaft updateCallbackDone der ViewTransition-Schnittstelle liefert ein Promise<undefined>. Es wird erfüllt, wenn der an document.startViewTransition() übergebene Update-Callback fertig ist, also wenn sein Promise erfüllt wurde oder er synchron zurückgekehrt ist. Wirft der Callback einen Fehler oder wird sein Promise abgelehnt, wird auch updateCallbackDone mit demselben Grund abgelehnt.

Anders als ViewTransition.ready und ViewTransition.finished hängt updateCallbackDone nicht vom Erfolg der Animation ab. Wird der Übergang übersprungen, etwa mit skipTransition(), weil das Dokument verborgen ist oder weil die Snapshots nicht erstellt werden konnten, wird der Callback trotzdem ausgeführt und updateCallbackDone entsprechend erfüllt. Deshalb eignet sich die Eigenschaft gut, um auf die Zustandsänderung selbst zu reagieren und nicht auf die Animation.

Typische Anwendungen sind:

Folgeaktionen wie Fokus setzen, Analytics-Ereignisse senden oder Daten nachladen, sobald das neue DOM steht, ohne das Ende der Animation abzuwarten.
Fehler im Update-Callback gezielt abfangen und behandeln, zum Beispiel wenn ein fetch fehlschlägt.
Gleiches Verhalten mit und ohne Unterstützung für View Transitions, weil das DOM-Update in beiden Fällen stattfindet.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Wird erfüllt, wenn der Update-Callback fertig ist, und abgelehnt, wenn er einen Fehler wirft oder sein Promise abgelehnt wird.

Beispiele

Auf das fertige DOM-Update reagieren

const updateList = async () => {
  const res = await fetch('/api/items');
  const items = await res.json();
  document.querySelector('#list').innerHTML = items
    .map((i) => `<li>${i.name.replace(/</g, '&lt;')}</li>`)
    .join('');
};

const transition = document.startViewTransition(updateList);

await transition.updateCallbackDone;
console.log('DOM aktualisiert, Animation läuft ggf. noch');
document.querySelector('#list li')?.focus();

DOM aktualisiert, Animation läuft ggf. noch

Fehler im Update-Callback abfangen

const transition = document.startViewTransition(async () => {
  const res = await fetch('/api/fehlt');
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  document.body.dataset.state = 'geladen';
});

try {
  await transition.updateCallbackDone;
} catch (err) {
  console.error('Update fehlgeschlagen:', err.message);
  document.body.dataset.state = 'fehler';
}

Update fehlgeschlagen: HTTP 404

Einheitliches Verhalten mit Fallback ohne View-Transition-Unterstützung

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

const runUpdate = async (callback) => {
  if (!document.startViewTransition) {
    await callback();
    return;
  }
  const transition = document.startViewTransition(callback);
  // Wird auch erfüllt, wenn die Animation übersprungen wird
  await transition.updateCallbackDone;
};

await runUpdate(updateTheme);
console.log('Theme gewechselt:', document.documentElement.classList.contains('dark'));

Theme gewechselt: true

Reihenfolge der drei Promises

const transition = document.startViewTransition(() => {
  document.querySelector('h1').textContent = 'Neue Überschrift';
});

transition.updateCallbackDone.then(() => console.log('1: updateCallbackDone'));
transition.ready.then(() => console.log('2: ready'));
transition.finished.then(() => console.log('3: finished'));

1: updateCallbackDone 2: ready 3: finished

// Wichtig · Fallstricke

Unterschied zu ready/finished: ready wird abgelehnt, wenn die Animation nicht starten kann. updateCallbackDone hängt dagegen nur vom Callback ab. Wer wissen will, ob der Zustand wirklich gewechselt hat, sollte dieses Promise prüfen.
Unbehandelte Ablehnungen: Schlägt der Callback fehl, werden updateCallbackDone, ready und finished alle abgelehnt. Fehlt ein Handler, erscheint in der Konsole eine Warnung „Uncaught (in promise)“. Deshalb Fehler immer mit try/catch oder .catch() behandeln.
Kein Callback: Wird startViewTransition() ohne Callback aufgerufen, wird updateCallbackDone sofort erfüllt, sobald die Snapshots erstellt sind.
Lange Callbacks: Während der Callback läuft, ist die Seite „eingefroren“ (Rendering pausiert). Braucht er länger als etwa 4 Sekunden, bricht der Browser den Übergang mit einem TimeoutError ab. Langsame Netzwerkanfragen sollten deshalb möglichst vor startViewTransition() erledigt werden.
Browser-Kompatibilität: View Transitions im selben Dokument werden von Chromium ab Version 111, Safari ab 18 und Firefox ab 144 unterstützt. Deshalb immer mit if (document.startViewTransition) prüfen und einen Fallback vorsehen.

Siehe auch

Promise ServiceWorkerRegistration.updateViaCache ViewTransition.ready ViewTransition.transitionRoot ViewTransition.finished