new ScrollTimeline() — Methode · JavaScript-Referenz

Signatur

new ScrollTimeline(options)

Beschreibung

Der Konstruktor ScrollTimeline() gehört zur API Scroll-Driven Animations. Er erzeugt eine Zeitleiste, die nicht an die Uhrzeit gebunden ist, sondern an die Scrollposition eines Elements. Scrollt der Nutzer vom Anfang bis zum Ende des Containers, läuft die Zeitleiste von 0 % bis 100 %.

Die so erzeugte Zeitleiste übergibt man als timeline-Option an Element.animate() oder an den Konstruktor new Animation(effect, timeline). Damit lassen sich Fortschrittsbalken, Parallax-Effekte oder Einblendungen umsetzen, ohne scroll-Events abzufangen. Die Animation läuft dabei häufig im Compositor-Thread und bleibt dadurch auch bei ausgelastetem Haupt-Thread flüssig.

Über source legst du den Scroll-Container fest (Standard: document.scrollingElement), über axis die Scrollrichtung. Für Animationen, die davon abhängen, wie weit ein bestimmtes Element im sichtbaren Bereich liegt, eignet sich stattdessen ViewTimeline.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.source	Element \| null	document.scrollingElement	Der Scroll-Container, dessen Scrollposition den Fortschritt bestimmt. Bei `null` ist die Zeitleiste inaktiv.
$options.axis	"block" \| "inline" \| "x" \| "y"	"block"	Die Scrollachse. `block` und `inline` richten sich nach dem Schreibmodus, `x` und `y` sind physische Achsen.

Rückgabewert

Typ

ScrollTimeline

Beschreibung

Eine neue ScrollTimeline-Instanz. Ihre Eigenschaft currentTime liefert den Fortschritt als CSSUnitValue in Prozent.

Beispiele

Lesefortschrittsbalken für die ganze Seite

// &lt;div id="progress"&gt;&lt;/div&gt; ist oben fixiert und hat width: 100%
const bar = document.querySelector('#progress');

const timeline = new ScrollTimeline({
  source: document.documentElement,
  axis: 'block'
});

bar.animate(
  { transform: ['scaleX(0)', 'scaleX(1)'] },
  { timeline, fill: 'both' }
);

console.log(timeline.axis);

block

Horizontaler Scroll-Container mit Parallax-Effekt

const gallery = document.querySelector('.gallery');
const bg = document.querySelector('.gallery-bg');

const timeline = new ScrollTimeline({ source: gallery, axis: 'x' });

const animation = new Animation(
  new KeyframeEffect(bg,
    { transform: ['translateX(0)', 'translateX(-30%)'] },
    { fill: 'both' }
  ),
  timeline
);
animation.play();

Aktuellen Fortschritt auslesen mit Feature-Erkennung

if ('ScrollTimeline' in window) {
  const timeline = new ScrollTimeline();
  window.addEventListener('scrollend', () => {
    // currentTime ist ein CSSUnitValue, z. B. { value: 42.5, unit: 'percent' }
    const { value } = timeline.currentTime ?? { value: 0 };
    console.log(`Gescrollt: ${value.toFixed(1)} %`);
  });
} else {
  console.log('Scroll-Driven Animations nicht unterstützt');
}

Gescrollt: 42.5 %

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen die API ab Version 115, Safari seit Version 26. In Firefox ist sie nur hinter dem Flag layout.css.scroll-driven-animations.enabled verfügbar. Prüfe die Unterstützung vorher mit 'ScrollTimeline' in window oder binde ein Polyfill ein.
Kann der source-Container nicht scrollen (kein Überlauf), ist die Zeitleiste inaktiv und currentTime ist null.
Scroll-Zeitleisten haben keine Dauer in Millisekunden. Gib bei animate() deshalb keine duration in ms an, sonst verhalten sich Animationen in manchen Implementierungen unerwartet. Lass sie weg oder nutze 'auto'.
Setze fill: 'both', damit der Zustand am Anfang und am Ende des Scrollbereichs erhalten bleibt.
In CSS gibt es das Gegenstück animation-timeline: scroll(). Für einfache Fälle ist das oft die schlankere Lösung.

Siehe auch

Element.prototype.animate() new Animation() new CSSPositionValue() new ViewTimeline() new DocumentTimeline()