AnimationTimeline.duration — Eigenschaft · JavaScript-Referenz

Signatur

get AnimationTimeline.duration

Beschreibung

Die Eigenschaft duration des Interfaces AnimationTimeline aus der Web Animations API gibt an, wie weit eine Timeline höchstens reicht. Sie ist nur lesbar und hängt von der Art der Timeline ab.

Zeitbasierte Timelines wie DocumentTimeline (z. B. document.timeline) laufen ohne Ende weiter. Deshalb ist duration hier null.
Fortschrittsbasierte Timelines wie ScrollTimeline und ViewTimeline haben ein festes Ende. Hier ist duration ein CSSNumericValue mit dem Wert 100% (CSS.percent(100)).

Im Alltag nutzt man die Eigenschaft vor allem, um herauszufinden, ob eine Animation an eine fortschrittsbasierte Timeline gebunden ist. Das ist wichtig, weil sich Zeitangaben wie currentTime dann in Prozent statt in Millisekunden ausdrücken. Bibliotheken und Polyfills für Scroll-Driven Animations prüfen deshalb oft timeline.duration !== null.

Seit der Spezifikation für Scroll-Driven Animations können Zeitwerte in der Web Animations API auch CSSNumericValue-Objekte sein. Wer mit duration rechnen will, sollte den Wert über .value und .unit oder mit .to('percent') auslesen.

Rückgabewert

Typ

CSSNumericValue | null

Beschreibung

Bei fortschrittsbasierten Timelines (ScrollTimeline, ViewTimeline) ein CSSNumericValue mit 100%. Bei zeitbasierten Timelines wie DocumentTimeline der Wert null.

Beispiele

Dokument-Timeline hat keine Dauer

// Die Standard-Timeline des Dokuments läuft ohne Ende
console.log(document.timeline.duration);

null

Dauer einer ScrollTimeline auslesen

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

  const d = timeline.duration;
  console.log(d.toString());      // "100%"
  console.log(d.value, d.unit);   // 100 "percent"
} else {
  console.log('Scroll-Driven Animations werden nicht unterstützt');
}

100% 100 percent

Fortschritt einer Animation unabhängig vom Timeline-Typ anzeigen

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

const timeline = 'ScrollTimeline' in window
  ? new ScrollTimeline({ source: document.documentElement })
  : document.timeline;

const anim = box.animate(
  { transform: ['translateX(0)', 'translateX(300px)'] },
  { duration: 2000, fill: 'both', timeline }
);

const logProgress = () => {
  const t = anim.timeline;
  if (t.duration !== null) {
    // Fortschrittsbasiert: currentTime ist ein Prozentwert
    const current = anim.currentTime; // CSSUnitValue in %
    console.log(`Scroll-Fortschritt: ${current?.value?.toFixed(1)} %`);
  } else {
    // Zeitbasiert: currentTime in Millisekunden
    console.log(`Laufzeit: ${Math.round(anim.currentTime)} ms`);
  }
};

window.addEventListener('scroll', logProgress, { passive: true });

Scroll-Fortschritt: 42.7 % (je nach Scroll-Position)

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft gibt es in Chromium-Browsern ab Version 116, zusammen mit Scroll-Driven Animations. In Firefox steckt sie bislang hinter einem Flag. Safari unterstützt sie erst in neueren Versionen. Prüfe daher vorher mit 'duration' in AnimationTimeline.prototype, ob sie verfügbar ist.
Kein Zahlenwert: Der Rückgabewert ist ein CSSNumericValue und keine Zahl. Vergleiche wie duration === 100 ergeben daher immer false. Nutze stattdessen duration.value oder duration.to('percent').value.
Die Eigenschaft ist nur lesbar. Eine Zuweisung wird ignoriert, im Strict Mode wirft sie einen TypeError.
null bedeutet nicht, dass die Timeline inaktiv ist, sondern nur, dass sie kein Ende hat. Ob eine Timeline aktiv ist, erkennst du an currentTime === null.
Verwechsle die Eigenschaft nicht mit der duration in den Timing-Optionen einer Animation (effect.getTiming().duration). Diese beschreibt die Länge des Effekts, nicht die der Timeline.

Siehe auch

Element.prototype.animate() AnimationTimeline.currentTime Animation.timeline AnimationEvent.animation Animation.pending