Signatur
Beschreibung
Die schreibgeschützte Eigenschaft currentTime der Schnittstelle AnimationTimeline aus dem Web Animations API liefert die aktuelle Zeit der Zeitleiste. Alle Animationen, die an diese Zeitleiste gebunden sind, berechnen ihren Fortschritt aus diesem Wert. Wenn die Zeitleiste inaktiv ist, ist der Wert null.
Bei der Standard-Zeitleiste document.timeline (eine DocumentTimeline) ist der Wert eine Zahl in Millisekunden seit dem Time Origin des Dokuments, also sehr nah an performance.now(). Innerhalb eines Frames bleibt der Wert jedoch gleich: Er wird einmal pro Frame aktualisiert und nicht bei jedem Zugriff.
Bei scrollgesteuerten Zeitleisten (ScrollTimeline, ViewTimeline) ist der Wert kein Zeitwert, sondern ein CSSUnitValue in Prozent (z. B. CSS.percent(42)). Er gibt an, wie weit gescrollt wurde bzw. wie weit ein Element den sichtbaren Bereich durchquert hat.
Typische Einsatzfälle: mehrere Animationen genau gleichzeitig starten (über animation.startTime = document.timeline.currentTime), den Scrollfortschritt auslesen, ohne einen scroll-Listener zu brauchen, oder eigene Zeitmessungen auf die Zeitbasis der Animationen abstimmen.
Rückgabewert
DocumentTimeline: Millisekunden als number. ScrollTimeline/ViewTimeline: CSSUnitValue mit der Einheit percent. Bei inaktiver Zeitleiste: null.Beispiele
Aktuelle Dokument-Zeit auslesen
const t = document.timeline.currentTime;
console.log(`Zeitleiste: ${t.toFixed(1)} ms`);
console.log(`performance.now(): ${performance.now().toFixed(1)} ms`);Mehrere Animationen synchron starten
const boxes = document.querySelectorAll('.box');
const start = document.timeline.currentTime;
boxes.forEach((box, i) => {
const anim = box.animate(
[{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }],
{ duration: 1000, delay: i * 100, fill: 'forwards' }
);
// Gemeinsame Startzeit: alle laufen exakt im selben Takt
anim.startTime = start;
});Scrollfortschritt über ScrollTimeline lesen
if ('ScrollTimeline' in window) {
const timeline = new ScrollTimeline({
source: document.documentElement,
axis: 'block'
});
const log = () => {
const ct = timeline.currentTime; // CSSUnitValue oder null
if (ct !== null) {
console.log(`Gescrollt: ${ct.value.toFixed(0)} ${ct.unit}`);
}
requestAnimationFrame(log);
};
requestAnimationFrame(log);
} else {
console.log('ScrollTimeline wird nicht unterstützt');
}Auf inaktive Zeitleiste prüfen
const describe = (timeline) => {
const ct = timeline.currentTime;
if (ct === null) return 'inaktiv';
return typeof ct === 'number' ? `${Math.round(ct)} ms` : ct.toString();
};
console.log(describe(document.timeline));// Wichtig · Fallstricke
- Schreibgeschützt: Wenn man
currentTimeetwas zuweist, wird das ignoriert (im Strict Mode wirft es einenTypeError). Um eine einzelne Animation zu verschieben, setzt man stattdessenAnimation.currentTimeoderAnimation.startTime. - Immer mit
nullrechnen: Eine Zeitleiste kann inaktiv sein, zum Beispiel in einem Dokument ohne Browsing-Kontext oder bei einerScrollTimeline, deren Container nicht scrollbar ist. Rechnet man ohne Prüfung damit, entstehenNaN-Werte. - Typ hängt von der Zeitleiste ab: Scroll-Zeitleisten liefern einen
CSSUnitValueund keine Zahl. Arithmetik wiect + 10funktioniert dann nicht; man nutztct.valueoderct.to('percent'). - Ungenauigkeit durch Sicherheitsmaßnahmen: Browser runden oder verrauschen den Wert (wie
performance.now()), um Timing-Angriffe zu erschweren. Deshalb eignet er sich nicht für hochpräzise Messungen. - Kompatibilität:
document.timeline.currentTimefunktioniert in allen modernen Browsern.ScrollTimelineundViewTimelinegibt es in Chromium ab Version 115; in Safari und Firefox ist die Unterstützung neu bzw. noch hinter Flags. Deshalb vorher mit'ScrollTimeline' in windowprüfen.