new DocumentTimeline() — Methode · JavaScript-Referenz

Signatur

new DocumentTimeline(options)

Beschreibung

Der Konstruktor DocumentTimeline() der Web Animations API erzeugt eine neue Zeitleiste, die an das aktive Dokument des aktuellen Browsing-Kontexts gebunden ist. Sie läuft im selben Takt wie die Standard-Zeitleiste document.timeline, kann aber über originTime einen verschobenen Nullpunkt haben.

Nützlich ist das vor allem, wenn mehrere Animationen auf einen gemeinsamen, selbst festgelegten Startzeitpunkt bezogen werden sollen, etwa „alles läuft ab dem Moment, in dem der Nutzer geklickt hat“. Der Zeitwert einer solchen Zeitleiste ist ungefähr document.timeline.currentTime - originTime. Setzt man für Animationen auf dieser Zeitleiste startTime, beziehen sich die Werte auf diesen eigenen Nullpunkt.

Eine eigene Zeitleiste übergibt man als zweites Argument an new Animation(effect, timeline) oder weist sie später über animation.timeline zu. Anhalten, beschleunigen oder zurückspulen lässt sich eine DocumentTimeline selbst nicht. Das geht nur mit den einzelnen Animation-Objekten.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Konfigurationsobjekt.
$options.originTime	number (DOMHighResTimeStamp)	0	Nullpunkt der neuen Zeitleiste in Millisekunden, gemessen ab dem Zeitursprung des Dokuments (`performance.timeOrigin`, gleiche Skala wie `performance.now()` und `document.timeline.currentTime`).

Rückgabewert

Typ

DocumentTimeline

Beschreibung

Eine neue DocumentTimeline-Instanz, deren currentTime relativ zu originTime gemessen wird.

Beispiele

Zeitleiste mit Nullpunkt „jetzt“ anlegen

const timeline = new DocumentTimeline({ originTime: document.timeline.currentTime });

setTimeout(() => {
  // Zeit seit dem Anlegen der Zeitleiste
  console.log(Math.round(timeline.currentTime));
}, 1000);

ca. 1000

Animation mit 500 ms Verzögerung über eine eigene Zeitleiste

const box = document.querySelector('.box');

const effect = new KeyframeEffect(
  box,
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 1000, fill: 'forwards', easing: 'ease-out' }
);

// Nullpunkt liegt 500 ms in der Zukunft
const timeline = new DocumentTimeline({
  originTime: document.timeline.currentTime + 500
});

const animation = new Animation(effect, timeline);
animation.startTime = 0; // startet, sobald die Zeitleiste 0 erreicht

animation.finished.then(() => console.log('Fertig'));

Fertig (nach ca. 1,5 s)

Mehrere Animationen an einem Klick-Zeitpunkt ausrichten

const items = document.querySelectorAll('.list-item');

document.querySelector('#start').addEventListener('click', (event) => {
  // event.timeStamp nutzt dieselbe Zeitskala wie performance.now()
  const timeline = new DocumentTimeline({ originTime: event.timeStamp });

  items.forEach((el, i) => {
    const effect = new KeyframeEffect(
      el,
      [{ opacity: 0, transform: 'translateY(20px)' }, { opacity: 1, transform: 'none' }],
      { duration: 400, fill: 'both' }
    );
    const anim = new Animation(effect, timeline);
    anim.startTime = i * 100; // gestaffelt ab dem Klick
  });
});

// Wichtig · Fallstricke

Kein Pausieren der Zeitleiste: Eine DocumentTimeline hat weder pause() noch playbackRate. Steuern lassen sich nur die einzelnen Animationen.
play() vs. startTime: animation.play() nimmt die aktuelle Zeit der Zeitleiste als Startpunkt. Ein verschobener originTime wirkt sich deshalb erst aus, wenn man startTime selbst setzt.
Einheit: originTime wird in Millisekunden auf der Skala von performance.now() angegeben, nicht als Unix-Zeitstempel wie bei Date.now().
Negative Zeitwerte: Liegt originTime in der Zukunft, ist currentTime zunächst negativ. Ist das Dokument nicht aktiv, etwa in einem getrennten iframe, ist currentTime null.
Kompatibilität: Der Konstruktor ist deutlich später in die Browser gekommen als document.timeline. Bei älteren Browsern vorher prüfen, z. B. mit typeof DocumentTimeline === 'function'. Die Option timeline in element.animate() wird nicht überall unterstützt, daher besser new Animation(effect, timeline) verwenden.

Siehe auch

new Animation() Element.prototype.animate() new DocumentFragment() new ScrollTimeline() new ViewTimeline()