Signatur
Beschreibung
DocumentTimeline ist eine Zeitleiste der Web Animations API und erbt von AnimationTimeline. Sie liefert den Zeitbezug, nach dem Animationen ihre Fortschritte berechnen. Jedes Dokument hat eine Standard-Zeitleiste, die über document.timeline abrufbar ist. Alle Animationen, die mit Element.animate() oder über CSS-Animationen und -Übergänge entstehen, laufen standardmäßig auf dieser Zeitleiste.
Die aktuelle Zeit der Zeitleiste steht in currentTime (geerbt von AnimationTimeline). Sie wird in Millisekunden angegeben und beginnt beim Ursprung der Zeitleiste. Bei der Standard-Zeitleiste ist das der Zeitursprung des Dokuments, also derselbe Wert, auf den sich performance.now() bezieht. Während eines Frames bleibt der Wert konstant. Dadurch laufen alle Animationen synchron.
Mit dem Konstruktor new DocumentTimeline({ originTime }) legen Sie eigene Zeitleisten an, deren Ursprung gegenüber der Standard-Zeitleiste verschoben ist. Das ist nützlich, wenn eine Gruppe von Animationen einen gemeinsamen, verzögerten Startpunkt bekommen soll oder wenn Zeitangaben relativ zu einem bestimmten Ereignis berechnet werden sollen. Eine eigene Zeitleiste übergeben Sie dem Konstruktor new Animation(effect, timeline) oder weisen sie animation.timeline zu.
- Konstruktor:
new DocumentTimeline(options) - Eigenschaft (geerbt):
currentTime:number | null, schreibgeschützt
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | object | {} | Optionales Konfigurationsobjekt für den Konstruktor new DocumentTimeline(). |
| $options.originTime | number | 0 | Ursprung der neuen Zeitleiste in Millisekunden, relativ zum Zeitursprung des Dokuments (dieselbe Basis wie bei performance.now()). Die currentTime der neuen Zeitleiste entspricht document.timeline.currentTime - originTime. |
Rückgabewert
DocumentTimeline-Instanz zurück. Ihre currentTime ist ein number in Millisekunden oder null, solange die Zeitleiste inaktiv ist.Beispiele
Standard-Zeitleiste auslesen
// Die Standard-Zeitleiste des Dokuments
const timeline = document.timeline;
console.log(timeline instanceof DocumentTimeline);
console.log(`Aktuelle Zeit: ${Math.round(timeline.currentTime)} ms`);
// Gleiche Zeitbasis wie performance.now()
console.log(Math.abs(timeline.currentTime - performance.now()) < 50);Eigene Zeitleiste mit verschobenem Ursprung anlegen
// Ursprung: 2 Sekunden ab jetzt
const origin = document.timeline.currentTime + 2000;
const delayedTimeline = new DocumentTimeline({ originTime: origin });
// Am Anfang ist currentTime negativ
console.log(Math.round(delayedTimeline.currentTime));
const box = document.querySelector('.box');
const effect = new KeyframeEffect(
box,
[{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
{ duration: 1000, fill: 'forwards' }
);
// Die Animation läuft auf der eigenen Zeitleiste
const animation = new Animation(effect, delayedTimeline);
animation.startTime = 0; // startet, wenn die Zeitleiste 0 erreicht, also nach etwa 2 s
Mehrere Animationen synchron an einem gemeinsamen Startpunkt ausrichten
const items = document.querySelectorAll('.list-item');
// Gemeinsame Zeitleiste, Ursprung = jetzt
const sharedTimeline = new DocumentTimeline({
originTime: document.timeline.currentTime
});
items.forEach((el, i) => {
const anim = el.animate(
[{ opacity: 0 }, { opacity: 1 }],
{ duration: 400, fill: 'both' }
);
anim.timeline = sharedTimeline;
anim.startTime = i * 100; // 100 ms Versatz je Element
});
console.log(`Gestartet: ${items.length} Animationen`);// Wichtig · Fallstricke
- Einheit und Zeitbasis:
currentTimeundoriginTimesind Millisekunden relativ zum Zeitursprung des Dokuments. Sie sind keine Unix-Zeitstempel wie beiDate.now(). - Konstant pro Frame: Innerhalb eines Frames liefert
currentTimeimmer denselben Wert. Für exakte Messungen istperformance.now()daher besser geeignet. nullmöglich: Ist die Zeitleiste inaktiv (z. B. in einem Dokument ohne Browsing-Kontext), istcurrentTimenull. Prüfen Sie den Wert, bevor Sie damit rechnen.- Genauigkeit: Zum Schutz vor Timing-Angriffen (Spectre, Fingerprinting) runden Browser den Zeitwert ab. In Firefox geschieht das bei
privacy.resistFingerprintingteils auf 100 ms oder noch gröber. - Kompatibilität:
document.timelineund der Konstruktor werden seit etwa 2020 von allen modernen Browsern unterstützt. Scroll- und View-Zeitleisten (ScrollTimeline,ViewTimeline) sind eigene Unterklassen vonAnimationTimelineund werden nicht überall unterstützt.