Document.timeline — Eigenschaft · JavaScript-Referenz

Signatur

Document.timeline

Beschreibung

Die Eigenschaft document.timeline gibt ein DocumentTimeline-Objekt zurück. Es ist die Standard-Zeitleiste des Dokuments. Alle Animationen, die mit Element.animate() oder new Animation(effect) ohne eigene Timeline erzeugt werden, laufen automatisch auf dieser Zeitleiste. Auch CSS-Animationen und CSS-Übergänge sind an sie gebunden.

Das wichtigste Merkmal ist currentTime. Der Wert gibt in Millisekunden an, wie viel Zeit seit dem Start der Zeitleiste vergangen ist. Die Zeitleiste startet ungefähr zu dem Zeitpunkt, an dem das Dokument zu laden beginnt (performance.timeOrigin). Der Wert entspricht damit in etwa performance.now(), wird aber nur einmal pro Frame aktualisiert. Deshalb eignet er sich gut, um mehrere Animationen genau aufeinander abzustimmen, zum Beispiel über animation.startTime.

Man verwendet document.timeline vor allem, um den Start mehrerer Animationen gemeinsam festzulegen, um Animationen ausdrücklich an die Dokumentzeit zu binden (etwa im Gegensatz zu einer ScrollTimeline) oder um die aktuelle Animationszeit für eigene Berechnungen abzufragen.

Rückgabewert

Typ

DocumentTimeline

Beschreibung

Die Standard-Zeitleiste des Dokuments. Ihre Eigenschaft currentTime ist vom Typ number | null und wird in Millisekunden angegeben. Sie ist null, wenn die Zeitleiste inaktiv ist, zum Beispiel in einem Dokument ohne Browsing-Kontext.

Beispiele

Aktuelle Zeit der Dokument-Zeitleiste abfragen

const timeline = document.timeline;
console.log(timeline instanceof DocumentTimeline);
console.log(`Zeitleiste läuft seit ${Math.round(timeline.currentTime)} ms`);

true Zeitleiste läuft seit 1532 ms

Mehrere Animationen genau gleichzeitig starten

const boxes = document.querySelectorAll('.box');
const start = document.timeline.currentTime + 500; // Start in 500 ms

boxes.forEach((box, i) => {
  const anim = box.animate(
    [{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }],
    { duration: 1000, delay: i * 100, fill: 'forwards' }
  );
  // Alle Animationen beziehen sich auf dieselbe Startzeit
  anim.startTime = start;
});

Animation ausdrücklich an die Dokument-Zeitleiste binden

const el = document.querySelector('#logo');
const effect = new KeyframeEffect(
  el,
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 800, easing: 'ease-out' }
);
const animation = new Animation(effect, document.timeline);
animation.play();

console.log(animation.timeline === document.timeline);

true

Eigene Zeitleiste mit Versatz im Vergleich zur Standard-Zeitleiste

// Zeitleiste, die 2 Sekunden nach dem Zeitursprung beginnt
const delayed = new DocumentTimeline({ originTime: 2000 });

requestAnimationFrame(() => {
  console.log('Standard:', Math.round(document.timeline.currentTime));
  console.log('Versetzt:', Math.round(delayed.currentTime));
});

Standard: 3200 Versetzt: 1200

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an document.timeline hat keine Wirkung. Für eine eigene Zeitbasis erzeugt man mit new DocumentTimeline({ originTime }) eine neue Zeitleiste.
Kann null sein: currentTime ist null, solange die Zeitleiste inaktiv ist, etwa in Dokumenten aus DOMParser oder document.implementation.createHTMLDocument(). Deshalb vor Berechnungen auf null prüfen.
Aktualisierung pro Frame: Innerhalb eines Frames bleibt currentTime gleich. Für feine Zeitmessungen ist performance.now() besser geeignet.
Geringere Genauigkeit: Zum Schutz vor Timing-Angriffen runden Browser den Wert (Reduced Time Precision), besonders wenn die Seite nicht cross-origin-isoliert ist.
Hintergrund-Tabs: In inaktiven Tabs werden die Frames gedrosselt. Die Zeit läuft zwar weiter, Animationen werden aber seltener neu gezeichnet.
Kompatibilität: Alle modernen Browser unterstützen die Eigenschaft (Chrome/Edge 84+, Firefox 75+, Safari 13.1+). Im Internet Explorer fehlt sie. Bei Bedarf mit 'timeline' in document prüfen.

Siehe auch

Element.prototype.animate() Animation Performance.prototype.now() Document.title Document.domain