AnimationPlaybackEvent.timelineTime — Eigenschaft · JavaScript-Referenz

Signatur

AnimationPlaybackEvent.timelineTime

Beschreibung

Die Eigenschaft timelineTime eines AnimationPlaybackEvent enthält den Wert von animation.timeline.currentTime zu dem Moment, in dem das Ereignis (finish, cancel oder remove) in die Warteschlange gestellt wurde. Bei der Standard-Zeitleiste document.timeline ist das die Zeit in Millisekunden seit dem Start der Zeitleiste des Dokuments, also ungefähr seit dem Laden der Seite.

Anders als currentTime des Ereignisses, das die lokale Zeit der Animation angibt (Position innerhalb der Animation), beschreibt timelineTime die globale Zeit der Zeitleiste. Damit lassen sich mehrere Animationen zeitlich zueinander in Beziehung setzen, etwa um zu messen, wie viel Zeit zwischen dem Ende zweier Animationen vergangen ist, oder um Folgeanimationen exakt auf einen Zeitpunkt der Zeitleiste zu synchronisieren.

Der Wert ist eine Momentaufnahme: Da das Ereignis erst asynchron ausgeliefert wird, kann document.timeline.currentTime beim Ausführen des Handlers bereits größer sein. Für präzise Berechnungen sollte daher timelineTime statt eines erneuten Auslesens der Zeitleiste verwendet werden.

Rückgabewert

Typ

number | CSSNumberish | null

Beschreibung

Zeitwert der Zeitleiste in Millisekunden (bei document.timeline) oder null, wenn die Zeitleiste inaktiv war bzw. die Animation keiner Zeitleiste zugeordnet ist. Bei Scroll-getriebenen Zeitleisten kann ein CSSUnitValue in Prozent geliefert werden.

Beispiele

Zeitleistenzeit beim Ende einer Animation auslesen

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

animation.addEventListener('finish', (event) => {
  console.log('Animationszeit:', event.currentTime);
  console.log('Zeitleistenzeit:', event.timelineTime);
});

Animationszeit: 1000 Zeitleistenzeit: 2345.6 (abhängig vom Seitenstart)

Abstand zwischen zwei Animationsenden messen

const [a, b] = document.querySelectorAll('.item');
const keyframes = [{ opacity: 0 }, { opacity: 1 }];

const animA = a.animate(keyframes, { duration: 800 });
const animB = b.animate(keyframes, { duration: 1200, delay: 200 });

const waitFinish = (anim) =>
  new Promise((resolve) =>
    anim.addEventListener('finish', (e) => resolve(e.timelineTime), { once: true })
  );

const [endA, endB] = await Promise.all([waitFinish(animA), waitFinish(animB)]);
console.log(`B endete ${Math.round(endB - endA)} ms nach A`);

B endete 600 ms nach A

Folgeanimation exakt an der Zeitleiste ausrichten

const el = document.querySelector('#banner');
const intro = el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 500, fill: 'forwards' });

intro.onfinish = (event) => {
  if (event.timelineTime === null) return; // inaktive Zeitleiste
  const pulse = el.animate(
    [{ transform: 'scale(1)' }, { transform: 'scale(1.05)' }, { transform: 'scale(1)' }],
    { duration: 600, iterations: 3 }
  );
  // Startzeit auf den Endzeitpunkt des Intros setzen – ohne Verzögerung durch die Ereigniswarteschlange
  pulse.startTime = event.timelineTime;
};

Bei Abbruch protokollieren

const anim = document.body.animate([{ background: 'white' }, { background: 'gold' }], 2000);

anim.addEventListener('cancel', (event) => {
  // currentTime ist bei cancel immer null, timelineTime nicht unbedingt
  console.log(event.currentTime, typeof event.timelineTime);
});

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

null "number"

// Wichtig · Fallstricke

Nicht verwechseln: event.currentTime ist die lokale Animationszeit, event.timelineTime die globale Zeit der Zeitleiste.
Der Wert kann null sein (inaktive Zeitleiste, z. B. bei einer ScrollTimeline ohne scrollbaren Bereich) – vor Berechnungen prüfen.
Die Eigenschaft ist schreibgeschützt; beim manuellen Erzeugen per new AnimationPlaybackEvent(type, { timelineTime }) kann sie jedoch im Init-Objekt gesetzt werden.
Mit Scroll-getriebenen Animationen kann statt einer Zahl ein CSSNumberish-Wert (z. B. Prozent) zurückkommen; ältere Browser liefern ausschließlich number.
Werte sind zur Abwehr von Timing-Angriffen ggf. in der Genauigkeit reduziert (z. B. in Firefox mit privacy.reduceTimerPrecision).
Unterstützt in Chrome/Edge 84+, Firefox 63+, Safari 13.1+.

Siehe auch

Element.animate() AnimationPlaybackEvent.currentTime AnimationEvent.elapsedTime AnimationEvent.animationName Animation.playbackRate