Animation.ready — Eigenschaft · JavaScript-Referenz

Signatur

Animation.ready

Beschreibung

Animation.ready gibt ein Promise zurück, das mit dem Animation-Objekt selbst erfüllt wird, sobald keine Wiedergabe- oder Pausenaktion mehr aussteht. Nach play() oder pause() ist eine Animation oft noch kurz in einem ausstehenden Zustand (animation.pending === true), etwa weil der Browser sie erst mit dem nächsten Frame oder dem Compositor-Thread abstimmen muss. Das ready-Promise zeigt an, dass dieser Zustand vorbei ist und die Animation tatsächlich läuft bzw. pausiert ist.

Das ist nützlich, wenn du erst dann weiterarbeiten willst, wenn die Animation wirklich angelaufen ist: etwa um startTime auszulesen (vorher oft noch null), mehrere Animationen genau aufeinander abzustimmen oder Oberflächenzustände (z. B. einen Button) erst nach dem tatsächlichen Start umzuschalten.

Wichtig: Jedes Mal, wenn die Animation wieder in einen ausstehenden Zustand wechselt, erzeugt der Browser ein neues Promise. Ein früher gespeicherter Verweis auf animation.ready kann also schon erfüllt sein und bezieht sich dann nicht mehr auf den aktuellen Vorgang. Lies die Eigenschaft deshalb immer direkt nach dem Aufruf von play() oder pause() aus.

Wird eine ausstehende Wiedergabe durch cancel() abgebrochen, wird das aktuelle ready-Promise mit einem DOMException vom Typ AbortError abgelehnt.

Rückgabewert

Typ

Promise<Animation>

Beschreibung

Ein Promise, das mit dem Animation-Objekt selbst erfüllt wird, sobald die Animation nicht mehr aussteht. Bei cancel() während eines ausstehenden Vorgangs wird es mit einer AbortError-DOMException abgelehnt.

Beispiele

Auf den tatsächlichen Start einer Animation warten

const box = document.querySelector('.box');

const animation = box.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 1000, fill: 'forwards' }
);

console.log('pending:', animation.pending, 'startTime:', animation.startTime);

const anim = await animation.ready;
console.log('pending:', anim.pending, 'startTime ist gesetzt:', anim.startTime !== null);

pending: true startTime: null pending: false startTime ist gesetzt: true

Pause bestätigen und Oberfläche aktualisieren

const spinner = document.querySelector('.spinner');
const button = document.querySelector('#toggle');

const spin = spinner.animate(
  [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }],
  { duration: 800, iterations: Infinity }
);

button.addEventListener('click', async () => {
  button.disabled = true;
  if (spin.playState === 'running') {
    spin.pause();
  } else {
    spin.play();
  }
  // ready erst NACH pause()/play() auslesen – sonst altes Promise
  await spin.ready;
  button.textContent = spin.playState === 'paused' ? 'Fortsetzen' : 'Pausieren';
  button.disabled = false;
});

Abbruch durch cancel() abfangen

const el = document.querySelector('.toast');
const fadeIn = el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 500 });

fadeIn.ready
  .then(() => console.log('Animation läuft'))
  .catch((err) => console.log('Abgebrochen:', err.name));

// Sofort abbrechen, bevor die Animation bereit ist
fadeIn.cancel();

Abgebrochen: AbortError

Zwei Animationen synchron starten

const a = document.querySelector('#a').animate(
  [{ opacity: 0 }, { opacity: 1 }], { duration: 1000 }
);
const b = document.querySelector('#b').animate(
  [{ opacity: 0 }, { opacity: 1 }], { duration: 1000 }
);

await Promise.all([a.ready, b.ready]);
// Startzeiten angleichen, damit beide exakt gleich laufen
b.startTime = a.startTime;
console.log('Synchron:', a.startTime === b.startTime);

Synchron: true

// Wichtig · Fallstricke

Neues Promise pro Vorgang: Nach jedem erneuten play()/pause() kann ready ein anderes Promise-Objekt sein. Einen alten Verweis zu speichern und später abzuwarten, führt schnell zu Fehlern.
Unbehandelte Ablehnung: cancel() lehnt ein ausstehendes ready-Promise mit AbortError ab. Ohne .catch() erscheint dann eine „Uncaught (in promise)“-Meldung in der Konsole.
Nicht mit finished verwechseln: ready meldet den Start bzw. die bestätigte Pause, Animation.finished dagegen das Ende der Animation.
Ist die Animation nicht ausstehend, ist ready schon erfüllt – await kehrt dann im nächsten Microtask zurück.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari (ab 13.1) unterstützt. Für CSS-Animationen und -Übergänge bekommst du das Animation-Objekt über element.getAnimations().

Siehe auch

Animation Animation.finished Animation.pending Animation.prototype.play() Animation.prototype.pause() Animation.prototype.cancel() Element.prototype.animate() Animation.startTime