Animation.currentTime — Eigenschaft · JavaScript-Referenz

Signatur

Animation.currentTime

Beschreibung

Die Eigenschaft currentTime eines Animation-Objekts gibt an, an welcher Stelle der Zeitachse sich die Animation gerade befindet. Der Wert wird in Millisekunden angegeben und bezieht sich auf die eigene Zeit der Animation. Die Wiedergabegeschwindigkeit (playbackRate) ist dabei schon eingerechnet, startTime und delay ebenfalls. Bei einer Verzögerung (delay) von 500 ms beginnt der sichtbare Effekt also erst bei currentTime === 500.

Die Eigenschaft ist beschreibbar. Wenn Sie einen Wert zuweisen, springt die Animation sofort an diese Stelle („Seeking“). Das funktioniert auch, wenn die Animation pausiert ist oder gar nicht läuft. Typische Einsätze sind Fortschrittsbalken und Schieberegler für die Zeitachse, eine Steuerung per Scroll-Position oder das Ausrichten mehrerer Animationen aufeinander.

Der Wert ist null, wenn die Animation keine aktive Zeitachse hat, zum Beispiel nach cancel() oder solange noch keine Startzeit feststeht. Ist die Animation beendet, bleibt currentTime auf dem Endwert stehen (delay + duration × iterations + endDelay), bis sie erneut gestartet wird.

Parameter

Name	Typ	Default	Beschreibung
$value	number \| null		Nur beim Setzen: neue Zeitposition in Millisekunden. Wenn Sie `null` auf einer Animation mit Zeitachse setzen, wird ein `TypeError` geworfen.

Rückgabewert

Typ

number | null

Beschreibung

Die aktuelle Zeit der Animation in Millisekunden (kann eine Kommazahl sein) oder null, wenn die Animation inaktiv ist bzw. keine Zeitachse hat. Bei Zeitachsen, die per Scroll gesteuert werden (ScrollTimeline), kann der Wert ein CSSNumericValue in Prozent sein.

Beispiele

Aktuelle Zeit auslesen

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

setTimeout(() => {
  console.log(`Position: ${Math.round(anim.currentTime)} ms`);
}, 1000);

Position: 1000 ms (ungefähr)

Zeitachse mit einem Schieberegler steuern

// <input type="range" id="scrub" min="0" max="100" value="0">
const slider = document.querySelector('#scrub');
const anim = document.querySelector('.box').animate(
  [{ opacity: 0, transform: 'scale(0.5)' }, { opacity: 1, transform: 'scale(1)' }],
  { duration: 3000, fill: 'both' }
);
anim.pause();

const total = anim.effect.getComputedTiming().endTime;
slider.addEventListener('input', () => {
  anim.currentTime = (slider.valueAsNumber / 100) * total;
});

Fortschritt in Prozent anzeigen

const anim = document.querySelector('.loader').animate(
  [{ width: '0%' }, { width: '100%' }],
  { duration: 5000, fill: 'forwards' }
);
const label = document.querySelector('#progress');
const { endTime } = anim.effect.getComputedTiming();

const update = () => {
  const pct = Math.min(100, (anim.currentTime / endTime) * 100);
  label.textContent = `${pct.toFixed(0)} %`;
  if (anim.playState === 'running') requestAnimationFrame(update);
};
requestAnimationFrame(update);

await anim.finished;
console.log('Fertig bei', anim.currentTime, 'ms');

Fertig bei 5000 ms

Zwei Animationen synchronisieren

const a = document.querySelector('#a').animate(
  [{ rotate: '0deg' }, { rotate: '360deg' }],
  { duration: 4000, iterations: Infinity }
);
const b = document.querySelector('#b').animate(
  [{ rotate: '0deg' }, { rotate: '-360deg' }],
  { duration: 4000, iterations: Infinity }
);

// b auf denselben Zeitpunkt wie a bringen
b.currentTime = a.currentTime;

// Wichtig · Fallstricke

Kann null sein: Nach cancel() oder ohne Zeitachse (timeline === null) liefert die Eigenschaft null. Prüfen Sie das, bevor Sie mit dem Wert rechnen, sonst entstehen NaN-Werte.
Kein Rücksetzen auf null: Wenn Sie null zuweisen, obwohl die Animation eine Zeitachse hat, wird ein TypeError geworfen.
Der Wert wird nicht auf die Dauer begrenzt: Werte größer als die Gesamtdauer oder negative Werte sind erlaubt. Die Animation gilt dann je nach Richtung als beendet oder als noch nicht begonnen. Ob dann etwas zu sehen ist, hängt von fill ab.
Kommazahlen und Genauigkeit: Aus Datenschutzgründen (Schutz vor Timing-Angriffen) runden Browser Zeitwerte teilweise ab. Vergleichen Sie deshalb nicht mit === auf exakte Werte.
Seeking während der Wiedergabe: Setzen Sie currentTime, während die Animation läuft, wird startTime neu berechnet und die Animation läuft ab der neuen Position weiter. Eine pausierte Animation bleibt pausiert.
Scroll-gesteuerte Animationen: Bei ScrollTimeline bzw. ViewTimeline gibt die Eigenschaft Prozentwerte (CSSNumericValue) statt Millisekunden zurück.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari (ab 13.1) vollständig unterstützt. Für sehr alte Browser gibt es das Polyfill web-animations-js.

Siehe auch

Animation Animation.prototype.pause() Element.prototype.animate() Animation.startTime Animation.pending