Animation.finished — Eigenschaft · JavaScript-Referenz

Signatur

Animation.finished

Beschreibung

Animation.finished gehört zur Web Animations API und liefert ein Promise<Animation>. Dieses Promise wird erfüllt, sobald die Animation den Zustand "finished" erreicht, also ihr Ende (oder beim Rückwärtsabspielen ihren Anfang) erreicht hat. Der Erfüllungswert ist das Animation-Objekt selbst.

Mit der Eigenschaft lassen sich Abläufe nach einer Animation sauber mit await oder .then() formulieren, etwa ein Element nach dem Ausblenden entfernen, Animationen nacheinander abspielen oder auf das Ende mehrerer paralleler Animationen per Promise.all() warten. Das ist oft übersichtlicher als ein Listener für das finish-Event.

Wichtig: Wird die Animation mit cancel() abgebrochen, wird das Promise mit einer DOMException vom Typ AbortError abgelehnt. Danach erzeugt der Browser ein neues Promise. Das gilt auch, wenn eine bereits beendete Animation neu gestartet wird, zum Beispiel über play(), reverse() oder eine Änderung von currentTime. Jeder Zugriff auf finished gibt also das Promise des gerade laufenden Durchgangs zurück.

Rückgabewert

Typ

Promise<Animation>

Beschreibung

Ein Promise, das mit dem Animation-Objekt erfüllt wird, wenn die Animation fertig ist. Bei cancel() wird es mit einem AbortError abgelehnt.

Beispiele

Element nach dem Ausblenden entfernen

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

const hideToast = async () => {
  const anim = toast.animate(
    [{ opacity: 1 }, { opacity: 0 }],
    { duration: 300, easing: 'ease-out' }
  );
  await anim.finished;
  toast.remove();
  console.log('Toast entfernt');
};

hideToast();

Toast entfernt

Animationen nacheinander abspielen

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

const sequence = async () => {
  await box.animate([{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }], { duration: 500, fill: 'forwards' }).finished;
  await box.animate([{ transform: 'translateX(200px)' }, { transform: 'translateX(200px) rotate(90deg)' }], { duration: 400, fill: 'forwards' }).finished;
  console.log('Sequenz abgeschlossen');
};

sequence();

Sequenz abgeschlossen

Auf alle Animationen warten und Abbruch behandeln

const waitForAnimations = async (element) => {
  try {
    await Promise.all(element.getAnimations().map((a) => a.finished));
    console.log('Alle Animationen beendet');
  } catch (err) {
    if (err.name === 'AbortError') {
      console.log('Eine Animation wurde abgebrochen');
    } else {
      throw err;
    }
  }
};

const el = document.querySelector('.card');
const anim = el.animate([{ opacity: 0 }, { opacity: 1 }], 1000);
waitForAnimations(el);
setTimeout(() => anim.cancel(), 200);

Eine Animation wurde abgebrochen

// Wichtig · Fallstricke

Ablehnung bei cancel(): Ohne catch entsteht ein „Unhandled Promise Rejection“. Behandle AbortError deshalb gezielt.
Neues Promise pro Durchgang: Nach einem Neustart oder Abbruch gibt finished ein anderes Promise zurück. Wer eine alte Referenz zwischenspeichert, wartet auf den falschen Durchgang.
Endlose Animationen: Bei iterations: Infinity wird das Promise nie erfüllt, außer man ruft finish() auf. Wegen der unendlichen Dauer wirft finish() in diesem Fall allerdings einen InvalidStateError.
Pausierte Animationen halten das Promise offen, bis sie weiterlaufen und enden.
Das Promise wird asynchron erfüllt (als Microtask), nicht synchron im selben Frame, in dem die Animation endet.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome/Edge 84+, Firefox 63+, Safari 13.1+). Ältere Browser brauchen das Polyfill web-animations-js oder das finish-Event.

Siehe auch

Animation Animation.ready Animation.prototype.finish() Animation.prototype.cancel() Element.prototype.animate() Promise.all()