ViewTimeline.subject — Eigenschaft · JavaScript-Referenz

Signatur

ViewTimeline.subject

Beschreibung

Die Eigenschaft subject einer ViewTimeline gibt eine Referenz auf das Subjektelement zurück. Das ist das Element, dessen Sichtbarkeit im nächsten scrollbaren Vorfahren (dem Scroller) den Fortschritt der Zeitleiste steuert. Wenn das Element unten in den sichtbaren Bereich des Scrollers hineinkommt, steht der Fortschritt bei 0 %. Sobald es oben vollständig hinausgescrollt ist, liegt er bei 100 %.

Den Wert legst du beim Erzeugen über die Option subject im Konstruktor new ViewTimeline({ subject }) fest. Danach lässt er sich nicht mehr ändern. Nützlich ist die Eigenschaft vor allem, wenn eine Zeitleiste weitergereicht wird, etwa über animation.timeline, und du wissen willst, welches Element sie beobachtet. Das hilft auch beim Debuggen oder wenn ein Hilfscode mehrere Zeitleisten verwaltet.

Der Scroller, der zum Subjekt gehört, steht in der geerbten Eigenschaft ScrollTimeline.source. Wo das Subjekt beginnt und endet, gemessen als Scroll-Offset, liefern startOffset und endOffset.

Rückgabewert

Typ

Element | null

Beschreibung

Das Subjektelement der Zeitleiste. Das kann auch ein Pseudo-Element-Ursprung sein, wenn die Zeitleiste per CSS entstanden ist.

Beispiele

Subjekt einer neu erzeugten ViewTimeline auslesen

const box = document.querySelector('.box');

const timeline = new ViewTimeline({
  subject: box,
  axis: 'block'
});

console.log(timeline.subject === box);
console.log(timeline.subject.className);

true box

Einblend-Animation beim Scrollen und Subjekt prüfen

const card = document.querySelector('#card');

const animation = card.animate(
  [
    { opacity: 0, transform: 'translateY(40px)' },
    { opacity: 1, transform: 'translateY(0)' }
  ],
  {
    fill: 'both',
    timeline: new ViewTimeline({ subject: card }),
    rangeStart: 'entry 0%',
    rangeEnd: 'entry 100%'
  }
);

// Später, z. B. in einem Hilfsmodul:
const { subject, source } = animation.timeline;
console.log(`Subjekt: #${subject.id}, Scroller: ${source.tagName}`);

Subjekt: #card, Scroller: HTML

Fortschritt pro Subjekt protokollieren (mit Feature-Erkennung)

if ('ViewTimeline' in window) {
  const timelines = [...document.querySelectorAll('section')]
    .map((el) => new ViewTimeline({ subject: el }));

  const log = () => {
    for (const tl of timelines) {
      const progress = tl.currentTime?.value ?? 'inaktiv';
      console.log(tl.subject.id, progress);
    }
  };

  document.addEventListener('scrollend', log);
} else {
  console.warn('Scroll-getriebene Animationen werden nicht unterstützt.');
}

intro 12.5 features inaktiv ...

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie timeline.subject = el wird im nicht-strikten Modus stillschweigend ignoriert und löst im Strict Mode einen TypeError aus. Für ein anderes Subjekt musst du eine neue ViewTimeline erzeugen.
Browser-Kompatibilität: Chromium-Browser unterstützen die Eigenschaft ab Version 115. Firefox bietet sie nur hinter dem Flag layout.css.scroll-driven-animations.enabled an, Safari erst in neueren Versionen. Prüfe deshalb vorher mit 'ViewTimeline' in window oder setze ein Polyfill ein (z. B. scroll-timeline von flackr).
Wenn das Subjekt kein scrollbares Vorfahrenelement hat oder nicht angezeigt wird (display: none), ist die Zeitleiste inaktiv und currentTime ist null. subject verweist trotzdem weiter auf das Element.
Die Zeitleiste hält eine Referenz auf das Element. Entfernst du das Subjekt aus dem DOM, solltest du auch die zugehörigen Animationen abbrechen (animation.cancel()), damit kein Speicher unnötig belegt bleibt.

Siehe auch

Element.prototype.animate() ScrollTimeline.source ViewTimeline.endOffset ViewTimeline.startOffset Animation.effect