Signatur
Beschreibung
AnimationTimeline ist die abstrakte Basisschnittstelle für alle Zeitleisten der Web Animations API. Eine Zeitleiste stellt die Zeitquelle bereit, an die eine Animation gebunden ist. Aus ihrem Wert berechnet der Browser, welchen Fortschritt die Animation gerade hat.
Du kannst die Schnittstelle nicht direkt instanziieren. In der Praxis arbeitest du mit ihren Unterklassen:
DocumentTimeline: eine zeitbasierte Zeitleiste. Die Standard-Zeitleiste jedes Dokuments steht überdocument.timelinebereit.ScrollTimeline: Der Fortschritt folgt der Scroll-Position eines Scroll-Containers (Scroll-Driven Animations).ViewTimeline: Der Fortschritt folgt der Sichtbarkeit eines Elements in seinem Scroll-Container.
Die Schnittstelle definiert die schreibgeschützte Eigenschaft currentTime. Bei einer DocumentTimeline ist das eine Zahl in Millisekunden, bei Scroll-Zeitleisten ein CSSUnitValue in Prozent. Ist die Zeitleiste inaktiv, ist der Wert null. Neuere Browser haben außerdem duration. Diese Eigenschaft ist bei Scroll-Zeitleisten 100% und bei Dokument-Zeitleisten null.
Du brauchst AnimationTimeline vor allem, wenn du Animationen mit einer bestimmten Zeitquelle synchronisieren willst, wenn du Zeitpunkte für Animation.startTime berechnest oder wenn du Code schreibst, der mit beliebigen Zeitleisten-Typen umgehen soll.
Rückgabewert
document.timeline, animation.timeline, new DocumentTimeline() und new ScrollTimeline().Beispiele
Aktuelle Zeit der Dokument-Zeitleiste lesen
const timeline = document.timeline;
console.log(timeline instanceof AnimationTimeline); // true
console.log(typeof timeline.currentTime); // "number" (ms seit Laden des Dokuments)Mehrere Animationen synchron starten
const boxes = document.querySelectorAll('.box');
const start = document.timeline.currentTime + 500; // in 500 ms
boxes.forEach((box) => {
const anim = box.animate(
[{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }],
{ duration: 1000, fill: 'forwards' }
);
// Gemeinsamer Startzeitpunkt auf derselben Zeitleiste
anim.startTime = start;
});Scroll-gebundene Animation mit ScrollTimeline
const progressBar = document.querySelector('#progress');
if ('ScrollTimeline' in window) {
const timeline = new ScrollTimeline({
source: document.documentElement,
axis: 'block'
});
progressBar.animate(
[{ transform: 'scaleX(0)' }, { transform: 'scaleX(1)' }],
{ timeline, fill: 'both' }
);
window.addEventListener('scroll', () => {
// CSSUnitValue in Prozent, z. B. "42.5%"
console.log(String(timeline.currentTime));
}, { passive: true });
}Zeitleisten-Typ generisch auswerten
const describeTimeline = (timeline) => {
const t = timeline.currentTime;
if (t === null) return 'inaktiv';
return typeof t === 'number' ? `${t.toFixed(0)} ms` : `${t.value.toFixed(1)} ${t.unit}`;
};
const anim = document.body.animate([{ opacity: 1 }, { opacity: 0.5 }], 1000);
console.log(describeTimeline(anim.timeline));// Wichtig · Fallstricke
AnimationTimelineist abstrakt.new AnimationTimeline()wirft einenTypeError.currentTimekannnullsein, zum Beispiel wenn die Zeitleiste inaktiv ist, ein Scroll-Container nicht scrollbar ist oder das Dokument noch nicht aktiv ist. Prüfe das immer vor Berechnungen.- Der Typ von
currentTimehängt von der Zeitleiste ab:numberin Millisekunden beiDocumentTimeline,CSSNumericValuein Prozent beiScrollTimelineundViewTimeline. Code, der eine Zahl erwartet, geht bei Scroll-Zeitleisten kaputt. - Browser-Unterstützung:
DocumentTimelineundcurrentTimegibt es in allen modernen Browsern.ScrollTimelineundViewTimelinegibt es in Chromium seit Version 115. In Firefox stehen sie nur hinter einem Flag, in Safari noch nicht oder nur eingeschränkt. Prüfe die Unterstützung per Feature-Detection ('ScrollTimeline' in window). - Die Zeitauflösung von
currentTimekann aus Datenschutzgründen (Schutz vor Timing-Angriffen) vergröbert sein, ähnlich wie beiperformance.now().