Animation.timeline — Eigenschaft · JavaScript-Referenz

Signatur

Animation.timeline

Beschreibung

Die Eigenschaft timeline einer Animation gibt an, welche Zeitleiste den Fortschritt der Animation steuert. Standardmäßig ist das die Dokument-Zeitleiste document.timeline. Sie ist an die Zeit seit dem Laden der Seite gebunden. Wer eine Animation mit element.animate() oder new Animation(effect) ohne eigene Zeitleiste erzeugt, erhält automatisch diese Standard-Zeitleiste.

Durch Setzen von timeline lässt sich eine laufende Animation an eine andere Zeitleiste binden. Das ist vor allem bei scrollgesteuerten Animationen praktisch: Mit einer ScrollTimeline oder ViewTimeline hängt der Fortschritt nicht mehr von der Zeit ab, sondern von der Scrollposition oder davon, wie weit ein Element im sichtbaren Bereich ist. Man kann auch eine eigene DocumentTimeline mit originTime verwenden, um mehrere Animationen gemeinsam zu versetzen.

Wird timeline auf null gesetzt, gehört die Animation zu keiner Zeitleiste mehr. Sie ist dann inaktiv, bis sie z. B. über currentTime manuell gesteuert oder wieder an eine Zeitleiste gebunden wird. Beim Wechsel der Zeitleiste versucht der Browser, den Fortschritt der Animation beizubehalten. Bei einer laufenden Animation wird dazu startTime passend neu berechnet.

Parameter

Name	Typ	Default	Beschreibung
$wert (beim Setzen)	AnimationTimeline \| null	document.timeline	Neue Zeitleiste, z. B. `document.timeline`, eine `new DocumentTimeline()`, `ScrollTimeline` oder `ViewTimeline`. Mit `null` wird die Animation von jeder Zeitleiste gelöst.

Rückgabewert

Typ

AnimationTimeline | null

Beschreibung

Die aktuell zugeordnete Zeitleiste oder null, wenn die Animation an keine Zeitleiste gebunden ist.

Beispiele

Standard-Zeitleiste auslesen

const box = document.querySelector('.box');
const anim = box.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 1000 }
);

console.log(anim.timeline === document.timeline);
console.log(anim.timeline.constructor.name);

true DocumentTimeline

Fortschrittsbalken an die Scrollposition koppeln (ScrollTimeline)

const bar = document.querySelector('#progress');
const anim = bar.animate(
  [{ transform: 'scaleX(0)' }, { transform: 'scaleX(1)' }],
  { fill: 'both', easing: 'linear' }
);

if ('ScrollTimeline' in window) {
  // Fortschritt folgt dem Scrollen der gesamten Seite
  anim.timeline = new ScrollTimeline({
    source: document.documentElement,
    axis: 'block'
  });
} else {
  console.warn('ScrollTimeline nicht unterstützt – normale Zeitsteuerung aktiv');
}

Animation von der Zeitleiste lösen und manuell steuern

const el = document.querySelector('.spinner');
const anim = el.animate(
  [{ rotate: '0deg' }, { rotate: '360deg' }],
  { duration: 2000, fill: 'both' }
);

anim.timeline = null;       // keine automatische Zeitsteuerung mehr
anim.currentTime = 500;     // manuell auf 25 % springen
console.log(anim.timeline, anim.currentTime);

null 500

Eigene DocumentTimeline mit Zeitversatz

const verzoegert = new DocumentTimeline({ originTime: 2000 });
const anim = document.querySelector('.hint').animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 500, fill: 'both' }
);
anim.timeline = verzoegert;
console.log(anim.timeline instanceof DocumentTimeline);

true

// Wichtig · Fallstricke

Kompatibilität: Das Lesen von timeline funktioniert in allen modernen Browsern. Das Setzen und vor allem ScrollTimeline/ViewTimeline sind nicht überall verfügbar: Chromium unterstützt sie ab Version 115. In Firefox waren sie lange nur hinter einem Flag verfügbar, und Safari unterstützt sie erst seit kurzem. Deshalb vorher mit 'ScrollTimeline' in window prüfen.
Bei scrollgesteuerten Zeitleisten wird die Dauer in Prozent gemessen, nicht in Millisekunden. Dann duration weglassen oder 'auto' verwenden. Werte wie currentTime werden als CSSNumericValue (Prozent) geliefert.
Mit timeline = null ist die Animation inaktiv. play() startet sie dann nicht sichtbar, solange currentTime nicht gesetzt ist.
Bei CSS-Animationen (CSSAnimation) lässt sich die Zeitleiste auch deklarativ über animation-timeline festlegen. Wird timeline per Skript gesetzt, überschreibt das die CSS-Angabe für diese Animation.
Ist die Scroll-Quelle nicht scrollbar (kein Überlauf), ist die Zeitleiste inaktiv und die Animation zeigt keinen Fortschritt.

Siehe auch

Animation Element.animate() Animation.pending Animation.startTime Animation.effect