Signatur
Beschreibung
Die schreibgeschützte Eigenschaft startOffset einer ViewTimeline gibt die Scroll-Position an, an der die Timeline beginnt, also 0 % Fortschritt hat. Der Wert ist ein CSSNumericValue, in der Praxis meist ein CSSUnitValue in Pixeln (px). Er wird vom Anfang des scrollbaren Inhalts im Scroll-Container gemessen.
Bei einer View-Timeline ist das der Punkt, an dem das beobachtete Element (subject) gerade am Ende des sichtbaren Bereichs („Scrollport“) auftaucht. Ein angegebener inset wird dabei schon eingerechnet. Zusammen mit endOffset beschreibt startOffset den gesamten Scrollbereich, in dem die Timeline aktiv ist.
Brauchbar ist die Eigenschaft vor allem, wenn du Scroll-Animationen mit eigener Logik verbinden willst. Beispiele: gezielt zu dem Punkt scrollen, an dem eine Animation beginnt, Debug-Ausgaben erzeugen oder den Fortschritt selbst berechnen. Der Wert ergibt sich aus dem aktuellen Layout. Er ändert sich also, wenn sich Fenstergröße, Inhalt oder Position des Elements ändern.
Rückgabewert
CSSUnitValue mit der Einheit px. Solange die Timeline inaktiv ist (z. B. wenn es keinen scrollbaren Vorfahren gibt oder das Element nicht angezeigt wird), kann der Wert fehlen oder unbrauchbar sein.Beispiele
Startposition einer View-Timeline auslesen
const subject = document.querySelector('.card');
const timeline = new ViewTimeline({
subject,
axis: 'block'
});
// Erst nach dem Layout auslesen
requestAnimationFrame(() => {
const start = timeline.startOffset;
console.log(start.toString());
console.log(start.value, start.unit);
});Wirkung von inset auf startOffset vergleichen
const subject = document.querySelector('#hero-image');
const ohneInset = new ViewTimeline({ subject });
const mitInset = new ViewTimeline({
subject,
inset: [CSS.px(0), CSS.px(200)] // unten 200px abziehen
});
requestAnimationFrame(() => {
console.log('ohne inset:', ohneInset.startOffset.toString());
console.log('mit inset:', mitInset.startOffset.toString());
});Zum Startpunkt der Animation scrollen
const subject = document.querySelector('.reveal');
const timeline = new ViewTimeline({ subject });
subject.animate(
{ opacity: [0, 1], transform: ['translateY(40px)', 'none'] },
{ timeline, fill: 'both', rangeStart: 'entry 0%', rangeEnd: 'entry 100%' }
);
document.querySelector('#jump').addEventListener('click', () => {
const { startOffset } = timeline;
if (startOffset && startOffset.unit === 'px') {
// timeline.source ist der Scroll-Container
timeline.source.scrollTo({ top: startOffset.value, behavior: 'smooth' });
}
});Eigene Fortschrittsberechnung mit Feature-Erkennung
if ('ViewTimeline' in window) {
const subject = document.querySelector('.section');
const tl = new ViewTimeline({ subject });
window.addEventListener('scroll', () => {
const start = tl.startOffset.to('px').value;
const end = tl.endOffset.to('px').value;
const pos = tl.source.scrollTop;
const progress = Math.min(1, Math.max(0, (pos - start) / (end - start)));
console.log(`Fortschritt: ${(progress * 100).toFixed(1)} %`);
}, { passive: true });
} else {
console.log('ViewTimeline wird nicht unterstützt');
}// Wichtig · Fallstricke
- Browserunterstützung: Scroll-gesteuerte Animationen gibt es in Chromium-Browsern ab Version 115 und in neueren Safari-Versionen. In Firefox sind sie nur hinter einem Flag verfügbar. Prüfe deshalb vor der Nutzung mit
'ViewTimeline' in window, ob die API vorhanden ist. - Vom Layout abhängig: Direkt nach
new ViewTimeline()ist der Wert unter Umständen noch nicht aktuell. Lies ihn deshalb erst nach dem Layout aus, etwa inrequestAnimationFrame. Nach Größenänderungen oder nachgeladenem Inhalt musst du ihn erneut abfragen, denn der Wert wird nicht zwischengespeichert. - Kein
number: Der Rückgabewert ist ein Objekt vom TypCSSNumericValue. Für Berechnungen brauchst du.value(beiCSSUnitValue) oder.to('px').value. Direkte Arithmetik wiestartOffset + 10liefert unsinnige Ergebnisse. - Nur lesbar: Eine Zuweisung hat keine Wirkung. Den Startpunkt verschiebst du über die Option
insetim Konstruktor oder überrangeStartbei der Animation. rangeStart/rangeEndeiner Animation ändernstartOffsetnicht. Die Eigenschaft beschreibt immer den gesamten Bereich der Timeline, entspricht also dem Bereichcover.