new AnimationPlaybackEvent() — Methode · JavaScript-Referenz

Signatur

new AnimationPlaybackEvent(type, options)

Beschreibung

Der Konstruktor AnimationPlaybackEvent() gehört zur Web Animations API und erzeugt ein Ereignisobjekt, das Zeitinformationen zur Wiedergabe einer Animation enthält. Der Browser erzeugt solche Ereignisse normalerweise selbst und löst sie auf einem Animation-Objekt aus, zum Beispiel wenn die Animation endet (finish), abgebrochen wird (cancel) oder automatisch entfernt wird (remove).

Selbst aufrufen muss man den Konstruktor vor allem in Tests (etwa um Handler wie animation.onfinish ohne echte Wartezeit zu prüfen), in Polyfills und in eigenen Abstraktionen, die ein animationsähnliches Verhalten nachbilden. Mit dispatchEvent() lässt sich das Ereignis dann auf einem beliebigen EventTarget auslösen, auch auf einer Animation.

Zusätzlich zu den üblichen Event-Optionen (bubbles, cancelable, composed) kann man im Optionsobjekt die Eigenschaften currentTime und timelineTime setzen. Beide sind nach der Erzeugung schreibgeschützt und haben den Standardwert null.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"finish"`, `"cancel"` oder `"remove"`. Beliebige andere Namen sind erlaubt.
$options	object	{}	Optionales Wörterbuch (`AnimationPlaybackEventInit`) mit folgenden Schlüsseln: `currentTime` (`number \| null`, Standard `null`): aktuelle Zeit der Animation in Millisekunden zum Zeitpunkt des Ereignisses. `timelineTime` (`number \| null`, Standard `null`): Zeitwert der Zeitleiste (`timeline.currentTime`) zum Zeitpunkt des Ereignisses. `bubbles`, `cancelable`, `composed` (`boolean`, Standard `false`): vom Interface `Event` geerbte Optionen.

Rückgabewert

Typ

AnimationPlaybackEvent

Beschreibung

Ein neues, noch nicht ausgelöstes AnimationPlaybackEvent-Objekt mit den angegebenen Werten für type, currentTime und timelineTime.

Beispiele

Ereignis erzeugen und Eigenschaften lesen

const evt = new AnimationPlaybackEvent('finish', {
  currentTime: 1000,
  timelineTime: 5234.5
});

console.log(evt.type);         // Ereignistyp
console.log(evt.currentTime);  // Zeit der Animation
console.log(evt.timelineTime); // Zeit der Zeitleiste
console.log(evt instanceof Event);

finish 1000 5234.5 true

Standardwerte ohne Optionsobjekt

const evt = new AnimationPlaybackEvent('cancel');

console.log(evt.currentTime, evt.timelineTime, evt.bubbles);

null null false

finish-Handler im Test ohne Wartezeit auslösen

const box = document.createElement('div');
document.body.append(box);

const animation = box.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 10000 }
);

animation.addEventListener('finish', (e) => {
  console.log(`Fertig bei ${e.currentTime} ms`);
});

// Ereignis im Test künstlich auslösen, statt 10 Sekunden zu warten
animation.dispatchEvent(
  new AnimationPlaybackEvent('finish', {
    currentTime: 10000,
    timelineTime: document.timeline.currentTime
  })
);

Fertig bei 10000 ms

Eigenes Wiedergabe-Ereignis in einer Komponente

class Sequencer extends EventTarget {
  #start = performance.now();

  stop() {
    const elapsed = performance.now() - this.#start;
    this.dispatchEvent(new AnimationPlaybackEvent('cancel', {
      currentTime: elapsed,
      timelineTime: document.timeline.currentTime
    }));
  }
}

const seq = new Sequencer();
seq.addEventListener('cancel', (e) => {
  console.log('Abgebrochen nach', Math.round(e.currentTime), 'ms');
});
setTimeout(() => seq.stop(), 500);

Abgebrochen nach 500 ms

// Wichtig · Fallstricke

Ein selbst ausgelöstes Ereignis hat isTrusted === false. Den Zustand der Animation ändert es nicht: animation.playState bleibt, wie er ist, und das Promise animation.finished wird dadurch nicht erfüllt.
currentTime und timelineTime sind nach der Erzeugung schreibgeschützt. Wer sie nachträglich zuweist, ändert nichts (im Strict Mode wird ein TypeError geworfen).
Beim cancel-Ereignis, das der Browser selbst auslöst, ist currentTime immer null, weil eine abgebrochene Animation keine aktuelle Zeit mehr hat.
In Browsern mit Scroll-gesteuerten Animationen (ScrollTimeline/ViewTimeline) können die Zeitwerte auch CSSNumberish-Werte wie Prozentangaben sein statt reiner Millisekunden. Man sollte sich also nicht blind auf number verlassen.
Kompatibilität: Der Konstruktor wird in aktuellen Versionen von Chrome, Edge, Firefox und Safari unterstützt. Sehr alte Browser (z. B. Internet Explorer) kennen ihn nicht. Bei Bedarf vorher mit typeof AnimationPlaybackEvent === 'function' prüfen.

Siehe auch

AnimationPlaybackEvent Animation Element.prototype.animate() EventTarget.prototype.dispatchEvent() Event