AnimationEvent.elapsedTime — Eigenschaft · JavaScript-Referenz

Signatur

AnimationEvent.elapsedTime

Beschreibung

elapsedTime ist eine schreibgeschützte Eigenschaft von AnimationEvent. Sie gibt als number (Gleitkommazahl) an, wie viele Sekunden eine CSS-Animation schon gelaufen ist, als das Ereignis ausgelöst wurde. Zeiten, in denen die Animation angehalten war (animation-play-state: paused), werden nicht mitgezählt. Eine Verzögerung über animation-delay zählt ebenfalls nicht dazu.

Der Wert hängt vom Ereignistyp ab:

animationstart: normalerweise 0. Bei einem negativen animation-delay startet die Animation mittendrin. Dann steht hier der Betrag der Verzögerung, höchstens aber die aktive Gesamtdauer.
animationiteration: die Zeit am Ende des gerade abgeschlossenen Durchlaufs, also ungefähr Durchlaufnummer × animation-duration.
animationend: die aktive Gesamtdauer, also animation-duration × animation-iteration-count.
animationcancel: die Zeit bis zum Abbruch der Animation.

Mit der Eigenschaft kann man z. B. ablesen, wie weit eine Animation fortgeschritten ist, Durchläufe mitzählen oder Messwerte zu Animationen erfassen. Das geht, ohne selbst Zeitstempel mit performance.now() zu verwalten. Die Werte stammen aus der Animationszeitachse und sind deshalb verlässlicher als eigene Zeitmessungen im Hauptthread.

Rückgabewert

Typ

number

Beschreibung

Die Laufzeit der Animation in Sekunden als Gleitkommazahl, z. B. 2.5. Die Zeit während animation-delay und in Pausen ist nicht enthalten.

Beispiele

Laufzeit bei Start, Durchlauf und Ende protokollieren

// CSS: .box { animation: pulse 1.5s ease-in-out 3; }
const box = document.querySelector('.box');

const log = (event) => {
  console.log(`${event.type}: ${event.animationName} nach ${event.elapsedTime}s`);
};

box.addEventListener('animationstart', log);
box.addEventListener('animationiteration', log);
box.addEventListener('animationend', log);

animationstart: pulse nach 0s animationiteration: pulse nach 1.5s animationiteration: pulse nach 3s animationend: pulse nach 4.5s

Negativer animation-delay: Animation startet mittendrin

// CSS: .loader { animation: spin 2s linear -0.5s infinite; }
const loader = document.querySelector('.loader');

loader.onanimationstart = (event) => {
  // Die Animation beginnt bei 0,5 s statt bei 0
  console.log('Startposition:', event.elapsedTime); 
};

Startposition: 0.5

Aktuellen Durchlauf aus elapsedTime berechnen

// CSS: .banner { animation: slide 2s ease 5; }
const banner = document.querySelector('.banner');
const duration = parseFloat(getComputedStyle(banner).animationDuration); // 2 (Sekunden)

const onIteration = (event) => {
  const round = Math.round(event.elapsedTime / duration);
  console.log(`Durchlauf ${round} abgeschlossen`);
  if (round >= 3) {
    // Nach drei Durchläufen nicht mehr zuhören
    banner.removeEventListener('animationiteration', onIteration);
  }
};

banner.addEventListener('animationiteration', onIteration);

Durchlauf 1 abgeschlossen Durchlauf 2 abgeschlossen Durchlauf 3 abgeschlossen

// Wichtig · Fallstricke

Einheit ist Sekunden, nicht Millisekunden. Das unterscheidet sich von event.timeStamp und performance.now(), die in Millisekunden messen. Vor einem Vergleich also umrechnen.
Gleitkomma-Ungenauigkeit: Werte wie 2.9999999 kommen vor. Deshalb nicht mit === vergleichen, sondern runden, z. B. mit Math.round() oder toFixed().
animation-delay und Pausen zählen nicht mit. elapsedTime ist also nicht die Zeit, die seit dem Setzen der Klasse vergangen ist.
Ereignisse wie animationiteration kommen nicht an, wenn das Element display: none hat oder aus dem DOM entfernt wird. Beim Entfernen lösen Browser stattdessen animationcancel aus, wo das unterstützt wird.
Die Eigenschaft ist schreibgeschützt. Für eigene Ereignisse lässt sich der Wert über den Konstruktor setzen: new AnimationEvent('animationend', { elapsedTime: 1 }).
Kompatibilität: wird von allen modernen Browsern unterstützt. Ältere WebKit-Versionen brauchten Präfixe wie webkitAnimationEnd.

Siehe auch

Animation.overallProgress AnimationEvent.animation AnimationEvent.animationName AnimationEvent.pseudoElement TransitionEvent.elapsedTime