AnimationPlaybackEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface AnimationPlaybackEvent extends Event

Beschreibung

AnimationPlaybackEvent ist die Event-Schnittstelle der Web Animations API. Ein solches Objekt bekommt man, wenn ein Animation-Objekt (etwa aus element.animate()) eines seiner Wiedergabe-Ereignisse auslöst: finish (Animation ist fertig), cancel (Animation wurde abgebrochen) oder remove (Animation wurde durch das automatische Entfernen ersetzter Animationen entfernt).

Zusätzlich zu den geerbten Eigenschaften von Event gibt es zwei nur lesbare Eigenschaften:

currentTime: aktuelle Zeit der Animation in Millisekunden zum Zeitpunkt des Ereignisses (number oder null, z. B. bei cancel).
timelineTime: Zeitwert der zugehörigen Zeitleiste (AnimationTimeline) zum Zeitpunkt des Ereignisses, oder null, wenn die Zeitleiste inaktiv ist.

Man verwendet das Interface vor allem dann, wenn man auf das Ende oder den Abbruch einer per JavaScript gesteuerten Animation reagieren möchte, z. B. um ein Element aus dem DOM zu entfernen, Zustände zu setzen oder Folgeanimationen zu starten. Für die meisten Fälle ist allerdings das Promise animation.finished die bequemere Alternative. Mit dem Konstruktor new AnimationPlaybackEvent(type, options) lassen sich solche Events außerdem selbst erzeugen, etwa für Tests.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses (Konstruktor), typischerweise `"finish"`, `"cancel"` oder `"remove"`.
$options	{ currentTime?: number\|null, timelineTime?: number\|null, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{}	Optionales Dictionary des Konstruktors. `currentTime` und `timelineTime` sind standardmäßig `null`; die übrigen Felder stammen aus `EventInit`.

Rückgabewert

Typ

AnimationPlaybackEvent

Beschreibung

Beim Konstruktor-Aufruf ein neues AnimationPlaybackEvent-Objekt; in Event-Handlern das vom Browser übergebene Event-Objekt.

Beispiele

Auf das Ende einer Animation reagieren (addEventListener)

const box = document.querySelector('.box');
const animation = box.animate(
  [{ opacity: 1 }, { opacity: 0 }],
  { duration: 500, fill: 'forwards' }
);

animation.addEventListener('finish', (event) => {
  console.log(event instanceof AnimationPlaybackEvent);
  console.log('Ende bei', event.currentTime, 'ms');
  box.remove(); // Element nach dem Ausblenden entfernen
});

true Ende bei 500 ms

Abbruch über die on-Property erkennen

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

spin.oncancel = (event) => {
  console.log(event.type, event.currentTime); // currentTime ist bei cancel null
};

// z. B. nachdem Daten geladen wurden
setTimeout(() => spin.cancel(), 2000);

cancel null

Event selbst erzeugen (z. B. für Tests)

const event = new AnimationPlaybackEvent('finish', {
  currentTime: 1200,
  timelineTime: 3456.7
});

console.log(event.type, event.currentTime, event.timelineTime);

finish 1200 3456.7

Automatisch entfernte Animationen protokollieren

const el = document.querySelector('.dot');

const moveTo = (x) => {
  const anim = el.animate({ transform: `translateX(${x}px)` }, { duration: 200, fill: 'forwards' });
  anim.onremove = (event) => {
    console.log('Animation ersetzt und entfernt:', event.type);
  };
  return anim;
};

// Mehrere fill-forwards-Animationen: ältere werden vom Browser entfernt
moveTo(100);
moveTo(200);

Animation ersetzt und entfernt: remove

// Wichtig · Fallstricke

Werte können null sein: Bei cancel ist currentTime immer null; timelineTime ist null, wenn die Zeitleiste inaktiv ist. Vor Berechnungen immer prüfen.
Kein Bubbling: Die Events werden am Animation-Objekt ausgelöst, nicht am animierten DOM-Element. Ein Listener auf dem Element oder auf document empfängt sie nicht. Für CSS-Animationen gibt es stattdessen animationend (AnimationEvent) am Element.
finished-Promise: Oft einfacher ist await animation.finished. Achtung: Das Promise wird bei cancel() mit einem AbortError abgelehnt.
Timing: finish wird asynchron (in einem späteren Animations-Frame) ausgelöst, nicht synchron beim Aufruf von animation.finish().
Kompatibilität: In allen modernen Browsern verfügbar (Chrome/Edge 84+, Firefox 63+, Safari 13.1+). Das remove-Event gibt es erst mit dem automatischen Entfernen von Animationen (Chrome 84, Firefox 75, Safari 14). Bei Scroll-getriebenen Zeitleisten (ScrollTimeline) können die Zeitwerte als CSSNumericValue statt Zahl erscheinen.

Siehe auch

Animation Element.prototype.animate() Animation.finished Event AnimationEvent