Animation.startTime — Eigenschaft · JavaScript-Referenz

Signatur

Animation.startTime

Beschreibung

Die Eigenschaft startTime des Animation-Interfaces ist ein Gleitkommawert mit doppelter Genauigkeit. Sie gibt an, zu welchem Zeitpunkt der zugehörigen Zeitleiste (meist document.timeline) die Wiedergabe der Animation beginnt bzw. begonnen hat. Der Wert wird in Millisekunden angegeben und bezieht sich auf timeline.currentTime, nicht auf Date.now() oder die Uhrzeit.

Die Eigenschaft ist les- und schreibbar. Beim Setzen wird die Animation so verschoben, dass ihre aktuelle Zeit (currentTime) sich aus (timeline.currentTime - startTime) * playbackRate ergibt. Damit lassen sich mehrere Animationen exakt synchronisieren: Man übernimmt einfach die startTime einer laufenden Animation für eine neue Animation. Ein Wert in der Zukunft verzögert den Start, ein Wert in der Vergangenheit lässt die Animation „mittendrin“ einsetzen.

Solange eine Animation pausiert, noch im Zustand pending (Start ausstehend) ist oder keine aktive Zeitleiste hat, liefert startTime den Wert null. Wird startTime auf null gesetzt, wird die Animation effektiv angehalten und behält ihre aktuelle Zeit.

Parameter

Name	Typ	Default	Beschreibung
$value	number \| null		Beim Setzen: neuer Startzeitpunkt in Millisekunden relativ zur Zeitleiste der Animation. `null` hebt den Startzeitpunkt auf (Animation hält an und behält `currentTime`).

Rückgabewert

Typ

number | null

Beschreibung

Startzeitpunkt in Millisekunden auf der Zeitleiste der Animation oder null, wenn die Animation pausiert, noch nicht gestartet (pending) oder ohne aktive Zeitleiste ist.

Beispiele

Startzeit einer laufenden Animation auslesen

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

// Direkt nach animate() ist der Start noch ausstehend
console.log(anim.startTime); // null

await anim.ready;
console.log(typeof anim.startTime, anim.startTime.toFixed(1));

null number 1532.4

Mehrere Animationen synchron starten

const keyframes = [{ opacity: 0.2 }, { opacity: 1 }];
const options = { duration: 1000, direction: 'alternate', iterations: Infinity };

const first = document.querySelector('#a').animate(keyframes, options);
await first.ready;

// Später hinzugefügtes Element exakt im Takt der ersten Animation laufen lassen
const second = document.querySelector('#b').animate(keyframes, options);
second.startTime = first.startTime;

console.log(second.currentTime === first.currentTime);

true

Start einer Animation um 500 ms verzögern

const el = document.querySelector('.hinweis');
const anim = el.animate(
  [{ transform: 'scale(0)' }, { transform: 'scale(1)' }],
  { duration: 400, fill: 'both' }
);

// Startzeitpunkt in die Zukunft der Dokument-Zeitleiste legen
anim.startTime = document.timeline.currentTime + 500;

console.log(anim.playState);

running

// Wichtig · Fallstricke

Bezugssystem: startTime bezieht sich auf animation.timeline.currentTime (bei document.timeline ab Laden des Dokuments), nicht auf Unix-Zeit. Werte aus Date.now() sind hier falsch.
null nach animate()/play(): Die Animation ist zunächst pending; die Startzeit wird erst im nächsten Frame festgelegt. Auf await animation.ready warten, bevor man sie liest.
Pausierte Animationen haben immer startTime === null; relevant ist dann currentTime.
Zum Schutz vor Timing-Angriffen (Fingerprinting) runden Browser den Wert teils auf gröbere Genauigkeit, z. B. Firefox mit privacy.reduceTimerPrecision.
Bei ScrollTimeline/ViewTimeline (Scroll-getriebene Animationen) kann der Wert ein CSSNumericValue in Prozent statt einer Zahl sein.
Das Setzen von startTime beendet einen ausstehenden play()- oder pause()-Vorgang sofort und löst ready auf.

Siehe auch

Animation Animation.currentTime Animation.playbackRate Animation.ready Animation.timeline Document.timeline Element.animate()