AnimationEffect.getComputedTiming() — Methode · JavaScript-Referenz

Signatur

AnimationEffect.prototype.getComputedTiming()

Beschreibung

getComputedTiming() liefert eine Momentaufnahme des Timings eines AnimationEffect, meist eines KeyframeEffect. Das zurückgegebene Objekt enthält alle Eigenschaften, die auch getTiming() liefert (delay, endDelay, fill, iterationStart, iterations, duration, direction, easing). Diese Werte sind aber aufgelöst: Aus duration: "auto" wird eine Zahl (bei Keyframe-Effekten 0), aus fill: "auto" wird "none".

Zusätzlich gibt es berechnete Werte, die den aktuellen Zustand beschreiben:

activeDuration: duration × iterations in Millisekunden.
endTime: delay + activeDuration + endDelay, also der Zeitpunkt, an dem der Effekt endet.
localTime: die aktuelle Zeit des Effekts in ms (entspricht in der Regel animation.currentTime) oder null, wenn keine Animation bzw. Zeitleiste zugeordnet ist.
progress: der Fortschritt innerhalb der aktuellen Iteration, von 0 bis 1, nach Anwendung von easing. Ist null, wenn der Effekt gerade nicht wirkt.
currentIteration: die aktuelle Iteration, bei 0 beginnend, oder null, wenn der Effekt nicht wirkt.

Typische Anwendungsfälle: Man synchronisiert Fortschrittsanzeigen, Zähler oder Audio mit einer laufenden Animation, liest das Timing von CSS-Animationen und -Übergängen über document.getAnimations() aus oder berechnet in Tests und beim Debuggen, in welcher Phase sich ein Effekt befindet.

Rückgabewert

Typ

ComputedEffectTiming

Beschreibung

Ein neues, einfaches Objekt (kein Live-Objekt) mit den aufgelösten Eigenschaften aus EffectTiming sowie endTime, activeDuration, localTime, progress und currentIteration. Alle Zeitangaben sind in Millisekunden.

Beispiele

Berechnetes Timing direkt nach dem Start auslesen

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

const animation = box.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 1000, iterations: 3, delay: 500 }
);

const timing = animation.effect.getComputedTiming();
console.log(timing.activeDuration, timing.endTime);
console.log(timing.localTime, timing.progress, timing.currentIteration);
console.log(timing.fill); // 'auto' wird aufgelöst

3000 3500 0 null null none

Fortschrittsbalken mit einer Animation synchronisieren

const ball = document.querySelector('.ball');
const bar = document.querySelector('progress');

const animation = ball.animate(
  [{ transform: 'scale(1)' }, { transform: 'scale(2)' }],
  { duration: 2000, iterations: 4, easing: 'ease-in-out' }
);

const update = () => {
  const { localTime, activeDuration, currentIteration } =
    animation.effect.getComputedTiming();

  if (localTime !== null) {
    // Gesamtfortschritt über alle Iterationen (linear, ohne Easing)
    bar.value = Math.min(localTime / activeDuration, 1);
    bar.title = `Durchlauf ${(currentIteration ?? 3) + 1} von 4`;
  }

  if (animation.playState !== 'finished') {
    requestAnimationFrame(update);
  }
};

requestAnimationFrame(update);

Laufende CSS-Animationen analysieren

// CSS: .spinner { animation: spin 1.2s linear infinite; }
const report = document.getAnimations().map((anim) => {
  const t = anim.effect.getComputedTiming();
  return {
    name: anim.animationName ?? anim.id,
    duration: t.duration,
    iterations: t.iterations,
    iteration: t.currentIteration,
    progress: t.progress?.toFixed(2) ?? '—'
  };
});

console.table(report);

┌─────────┬────────┬──────────┬────────────┬───────────┬──────────┐ │ (index) │ name │ duration │ iterations │ iteration │ progress │ │ 0 │ 'spin' │ 1200 │ Infinity │ 5 │ '0.42' │ └─────────┴────────┴──────────┴────────────┴───────────┴──────────┘

getTiming() und getComputedTiming() im Vergleich

const effect = new KeyframeEffect(
  document.body,
  [{ opacity: 1 }, { opacity: 0.5 }],
  { fill: 'auto' } // duration bleibt 'auto'
);

console.log(effect.getTiming().duration, effect.getTiming().fill);
console.log(effect.getComputedTiming().duration, effect.getComputedTiming().fill);
// Keine Animation zugeordnet, daher keine lokale Zeit
console.log(effect.getComputedTiming().localTime);

auto auto 0 none null

// Wichtig · Fallstricke

Momentaufnahme: Das Objekt wird nicht automatisch aktualisiert. Für Live-Werte muss die Methode erneut aufgerufen werden, z. B. in einer requestAnimationFrame-Schleife.
null-Werte: progress und currentIteration sind null, solange der Effekt nicht wirkt, zum Beispiel während eines delay ohne fill: "backwards" oder nach dem Ende ohne fill: "forwards". Vor dem Rechnen immer prüfen, z. B. mit ?? .
progress berücksichtigt das Easing und gilt nur für die aktuelle Iteration, nicht für die ganze Animation. Den Gesamtfortschritt berechnet man mit localTime / activeDuration.
Bei iterations: Infinity sind auch activeDuration und endTime gleich Infinity.
Zum Ändern des Timings ist updateTiming() zuständig. Änderungen am zurückgegebenen Objekt haben keine Wirkung.
Kompatibilität: Die Methode wird in Chrome/Edge, Firefox und Safari (ab 13.1) unterstützt. Sehr alte Browser brauchen das Polyfill web-animations-js.

Siehe auch

Element.animate() AnimationEffect.getTiming() AnimationEffect.updateTiming() SVGAnimationElement.getCurrentTime() SVGAnimationElement.getSimpleDuration()