Animation.overallProgress — Eigenschaft · JavaScript-Referenz

Signatur

Animation.overallProgress

Beschreibung

Die schreibgeschützte Eigenschaft overallProgress einer Animation gibt den Gesamtfortschritt bis zum Endzustand als Zahl zwischen 0 und 1 an. Sie bezieht sich auf alle Wiederholungen (iterations) und die Verzögerungen (delay, endDelay), nicht auf einen einzelnen Durchlauf. Eine Animation mit 3 Wiederholungen hat also nach dem ersten Durchlauf ungefähr einen overallProgress von 0.33.

Intern entspricht der Wert currentTime / endTime (auf 0–1 begrenzt), wobei endTime aus effect.getComputedTiming() stammt. Bisher musste man diese Rechnung selbst durchführen. Das war fehleranfällig, gerade bei scrollgesteuerten Animationen (ScrollTimeline/ViewTimeline), wo currentTime ein CSSNumericValue in Prozent statt Millisekunden ist. overallProgress funktioniert unabhängig vom Zeitleistentyp gleich.

Typische Anwendungsfälle sind Fortschrittsbalken, Prozentanzeigen, das Synchronisieren anderer UI-Elemente mit einer laufenden Animation und Analyse- bzw. Fehlersuch-Werkzeuge. Der Wert ist nicht durch Easing verzerrt: Er bildet den zeitlichen Fortschritt ab, nicht den visuellen Zustand der Eigenschaftswerte.

Rückgabewert

Typ

number | null

Beschreibung

Eine Zahl von 0 bis einschließlich 1 für den Gesamtfortschritt. null, wenn die Animation keinen Effekt hat oder ihre currentTime ungeklärt ist (z. B. ohne Zeitleiste oder nach cancel()). Beträgt die Endzeit des Effekts 0, ist der Wert 0 bei negativer aktueller Zeit, sonst 1.

Beispiele

Fortschrittsbalken für eine Animation mit mehreren Wiederholungen

// HTML: <div id="box"></div> <progress id="bar" max="1" value="0"></progress>
const box = document.getElementById('box');
const bar = document.getElementById('bar');

const anim = box.animate(
  [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }],
  { duration: 1000, iterations: 3, easing: 'ease-in-out' }
);

const update = () => {
  const p = anim.overallProgress;
  if (p !== null) {
    bar.value = p;
    bar.textContent = `${Math.round(p * 100)} %`;
  }
  if (anim.playState !== 'finished') requestAnimationFrame(update);
};
requestAnimationFrame(update);

anim.finished.then(() => console.log('Fertig:', anim.overallProgress));

Fertig: 1

Vergleich mit der manuellen Berechnung

const anim = document.body.animate(
  [{ opacity: 1 }, { opacity: 0.5 }],
  { duration: 2000, iterations: 2, delay: 1000 }
);
anim.pause();
anim.currentTime = 2500; // Endzeit = 1000 + 2 * 2000 = 5000 ms

const { endTime } = anim.effect.getComputedTiming();
const manuell = Math.min(Math.max(anim.currentTime / endTime, 0), 1);

console.log(anim.overallProgress); // 0.5
console.log(manuell);              // 0.5
console.log(anim.effect.getComputedTiming().progress); // Fortschritt der aktuellen Wiederholung

0.5 0.5 0.75

Scrollgesteuerte Animation mit Feature-Erkennung

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

if ('overallProgress' in Animation.prototype && 'ScrollTimeline' in window) {
  const anim = header.animate(
    [{ backgroundColor: '#fff' }, { backgroundColor: '#222' }],
    { fill: 'both', timeline: new ScrollTimeline({ source: document.documentElement }) }
  );

  window.addEventListener('scroll', () => {
    const p = anim.overallProgress ?? 0;
    document.title = `Gelesen: ${Math.round(p * 100)} %`;
  }, { passive: true });
} else {
  console.warn('overallProgress oder ScrollTimeline wird nicht unterstützt');
}

null nach cancel()

const anim = document.body.animate([{ opacity: 0 }, { opacity: 1 }], 500);
console.log(typeof anim.overallProgress); // 'number'
anim.cancel();
console.log(anim.overallProgress);

number null

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist relativ neu (Chrome/Edge ab 133). Firefox und Safari unterstützen sie erst in neueren Versionen. Prüfe vorher mit 'overallProgress' in Animation.prototype und rechne sonst selbst mit currentTime / getComputedTiming().endTime.
Auf null prüfen: Ohne Zeitleiste, ohne Effekt oder nach cancel() ist der Wert null. Nutze ?? 0 oder eine explizite Prüfung.
Unendliche Wiederholungen: Bei iterations: Infinity ist die Endzeit unendlich, deshalb bleibt overallProgress dauerhaft 0. Für den Fortschritt innerhalb eines Durchlaufs nutzt du effect.getComputedTiming().progress.
Verzögerungen zählen mit: delay und endDelay sind Teil der Endzeit. Während der Startverzögerung bleibt der Wert 0.
Kein Easing, keine Richtung: Der Wert zeigt den zeitlichen Fortschritt. Er berücksichtigt weder easing noch direction: 'reverse' im Sinne der dargestellten Werte. Bei negativer playbackRate sinkt er entsprechend.
Die Eigenschaft ist schreibgeschützt: Eine Zuweisung wird ignoriert (im Strict Mode gibt es einen TypeError). Um die Position zu ändern, setzt du currentTime.

Siehe auch

Animation Element.animate() PaymentResponse.shippingAddress Animation.currentTime Animation.effect