ScrollTimeline.source — Eigenschaft · JavaScript-Referenz

Signatur

ScrollTimeline.source

Beschreibung

Die Eigenschaft source einer ScrollTimeline gibt das Element zurück, dessen Scroll-Position die Zeitleiste antreibt. Scrollt dieser Scroller vom Anfang bis zum Ende seines Scrollbereichs, läuft der Fortschritt der Zeitleiste von 0 % bis 100 %. Angehängte Animationen laufen dabei im gleichen Maß mit.

Welcher Scroller verwendet wird, legen Sie im Konstruktor new ScrollTimeline({ source, axis }) fest. Lassen Sie source weg, gilt document.scrollingElement als Standard, meist also das <html>-Element. Später können Sie den Wert nur noch lesen. Für einen anderen Scroller brauchen Sie eine neue Zeitleiste.

In der Praxis ist die Eigenschaft beim Debuggen nützlich. Sie hilft auch, wenn eine Zeitleiste über animation.timeline weitergegeben wird und Sie wissen müssen, an welchen Container sie gebunden ist, etwa um Listener zu registrieren oder Messungen durchzuführen.

Rückgabewert

Typ

Element | null

Beschreibung

Das scrollbare Element, das die Zeitleiste antreibt. Gibt es keinen gültigen Scroller mehr (z. B. nach dem Entfernen des Elements aus dem DOM), kann eine inaktive Zeitleiste auftreten. Je nach Implementierung liefert source dann null.

Beispiele

Standard-Scroller auslesen

// Ohne source-Option wird das Dokument-Scrollelement verwendet
const timeline = new ScrollTimeline();
console.log(timeline.source === document.scrollingElement);
console.log(timeline.source.nodeName);

true HTML

Fortschrittsbalken an einen Container binden

const container = document.querySelector('#artikel');
const balken = document.querySelector('#fortschritt');

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

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

console.log(timeline.source.id);

artikel

Scroller einer bestehenden Animation ermitteln

const beschreibeTimeline = (animation) => {
  const tl = animation.timeline;
  if (typeof ScrollTimeline !== 'undefined' && tl instanceof ScrollTimeline) {
    const { source, axis } = tl;
    return `Scroll-gesteuert durch <${source?.nodeName.toLowerCase()}> (Achse: ${axis})`;
  }
  return 'Zeitgesteuert (DocumentTimeline)';
};

document.getAnimations().forEach((a) => console.log(beschreibeTimeline(a)));

Scroll-gesteuert durch <div> (Achse: block)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie timeline.source = el hat keine Wirkung und wirft im Strict Mode einen TypeError. Für einen anderen Scroller erzeugen Sie eine neue ScrollTimeline.
Kein Scrollbereich: Ist das Element nicht scrollbar (kein overflow oder kein überlaufender Inhalt), bleibt die Zeitleiste inaktiv (currentTime ist null), obwohl source gesetzt ist.
Browser-Kompatibilität: Scroll-gesteuerte Animationen sind noch nicht in allen Browsern verfügbar. Chrome/Edge unterstützen sie ab Version 115. Firefox bietet sie nur hinter einem Flag an. Prüfen Sie die Unterstützung vorab mit 'ScrollTimeline' in window oder CSS.supports('animation-timeline: scroll()').
Wird eine Zeitleiste in CSS über scroll() bzw. scroll-timeline definiert, zeigt source auf den tatsächlich aufgelösten Scroller (z. B. den nächsten scrollbaren Vorfahren).

Siehe auch

ScrollTimeline ScrollTimeline.axis ViewTimeline AnimationTimeline.currentTime Element.prototype.animate() CSPViolationReport.sourceFile