AnimationPlaybackEvent.currentTime — Eigenschaft · JavaScript-Referenz

Signatur

AnimationPlaybackEvent.currentTime

Beschreibung

Die schreibgeschützte Eigenschaft currentTime eines AnimationPlaybackEvent enthält die aktuelle Zeit der Animation, die das Ereignis ausgelöst hat. Gemessen wird zu dem Zeitpunkt, an dem das Ereignis in die Warteschlange gestellt wurde, nicht erst bei seiner Verarbeitung. Der Wert wird in Millisekunden angegeben und kann null sein.

AnimationPlaybackEvent-Objekte bekommt man über die Ereignisse finish, cancel und remove einer Animation (Web Animations API). So lässt sich zuverlässig feststellen, an welcher Stelle die Animation zum Zeitpunkt des Ereignisses stand. Das ist nützlich, wenn animation.currentTime sich bis zur Ausführung des Handlers schon geändert haben könnte, etwa durch einen erneuten Aufruf von play().

Bei einem finish-Ereignis entspricht der Wert normalerweise der Endzeit der Animation (Verzögerung + aktive Dauer + Endverzögerung). Bei einem cancel-Ereignis ist er null, weil eine abgebrochene Animation keine aktuelle Zeit mehr hat.

Rückgabewert

Typ

number | null

Beschreibung

Die aktuelle Zeit der Animation in Millisekunden zum Zeitpunkt des Einreihens des Ereignisses, oder null, wenn die Animation inaktiv war (z. B. nach cancel()).

Beispiele

Endzeit beim finish-Ereignis auslesen

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

animation.addEventListener('finish', (event) => {
  console.log('Animation beendet bei', event.currentTime, 'ms');
});

Animation beendet bei 1200 ms

currentTime ist beim Abbrechen null

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

spin.oncancel = (event) => {
  console.log('Abgebrochen, currentTime =', event.currentTime);
};

setTimeout(() => spin.cancel(), 500);

Abgebrochen, currentTime = null

Ereignis-Zeit und Timeline-Zeit vergleichen

const anim = document.body.animate(
  [{ opacity: 1 }, { opacity: 0.5 }],
  { duration: 500 }
);

anim.onfinish = (event) => {
  console.log({
    animationszeit: event.currentTime,
    timelineZeit: Math.round(event.timelineTime)
  });
};

{ animationszeit: 500, timelineZeit: 1734 } // timelineTime variiert

Eigenes Ereignis mit dem Konstruktor erzeugen

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

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

finish 750 2000

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.currentTime hat keine Wirkung und wirft im Strict Mode einen TypeError. Um die Position einer Animation zu ändern, nutzt man stattdessen animation.currentTime.
Auf null prüfen: Bei cancel ist der Wert null. Rechnet man ohne Prüfung damit weiter, entsteht leicht 0 oder NaN.
Momentaufnahme: Der Wert wird beim Einreihen des Ereignisses festgehalten. animation.currentTime kann bei der Ausführung des Handlers davon abweichen.
Nicht mit timelineTime verwechseln: timelineTime ist die Zeit der Zeitleiste (z. B. document.timeline), currentTime die lokale Zeit der Animation.
Typ: In neueren Spezifikationen (Scroll-gesteuerte Animationen) kann der Wert auch ein CSSNumberish sein, z. B. ein Prozentwert. Bei zeitbasierten Animationen ist er eine Zahl.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari (ab 13.1) unterstützt. Ältere Browser brauchen das Polyfill web-animations-js.

Siehe auch

Element.animate() AnimationPlaybackEvent.timelineTime AnimationTimeline.currentTime Animation.currentTime Animation.playbackRate