new AnimationEvent() — Methode · JavaScript-Referenz

Signatur

new AnimationEvent(type, options)

Beschreibung

Der Konstruktor AnimationEvent() erzeugt ein synthetisches Ereignisobjekt vom Typ AnimationEvent. Solche Ereignisse löst der Browser normalerweise selbst aus, wenn eine CSS-Animation (@keyframes + animation) startet, eine Wiederholung beendet, endet oder abgebrochen wird.

Selbst gebaute Instanzen sind vor allem nützlich für Unit- und Integrationstests (z. B. um Code zu prüfen, der auf animationend wartet, ohne echte Animationen abzuspielen), für Polyfills oder um Komponenten gezielt in einen Endzustand zu versetzen. Das Objekt wird mit EventTarget.dispatchEvent() an ein Element gesendet.

Über das options-Objekt lassen sich neben den allgemeinen Ereignis-Optionen (bubbles, cancelable, composed) die animationsspezifischen Eigenschaften animationName, elapsedTime und pseudoElement setzen. Diese sind danach schreibgeschützt.

Beachte: Anders als echte Browser-Ereignisse blubbern selbst erzeugte Events standardmäßig nicht – dafür muss bubbles: true explizit angegeben werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"animationstart"`, `"animationend"`, `"animationiteration"` oder `"animationcancel"`. Groß-/Kleinschreibung ist relevant.
$options	object	{}	Optionales Konfigurationsobjekt (erbt von `EventInit`).
$options.animationName	string	""	Wert der CSS-Eigenschaft `animation-name`, also der Name der `@keyframes`-Regel.
$options.elapsedTime	number	0	Laufzeit der Animation in Sekunden zum Zeitpunkt des Ereignisses (ohne Pausen, `animation-delay` wird berücksichtigt).
$options.pseudoElement	string	""	Name des Pseudo-Elements, auf dem die Animation läuft, beginnend mit `::` (z. B. `"::before"`); leer für das Element selbst.
$options.bubbles	boolean	false	Ob das Ereignis im DOM nach oben blubbert.
$options.cancelable	boolean	false	Ob `preventDefault()` Wirkung hat.
$options.composed	boolean	false	Ob das Ereignis die Shadow-DOM-Grenze überschreitet.

Rückgabewert

Typ

AnimationEvent

Beschreibung

Ein neues AnimationEvent-Objekt mit den übergebenen Eigenschaften, bereit für dispatchEvent().

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

const event = new AnimationEvent('animationend', {
  animationName: 'fadeIn',
  elapsedTime: 0.5,
  bubbles: true
});

console.log(event.type);          // Ereignistyp
console.log(event.animationName); // Keyframes-Name
console.log(event.elapsedTime);   // Sekunden
console.log(event instanceof Event);

animationend fadeIn 0.5 true

animationend manuell auslösen (z. B. Modal sofort schließen)

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

modal.addEventListener('animationend', (e) => {
  if (e.animationName === 'slideOut') {
    modal.remove();
    console.log(`Modal entfernt nach ${e.elapsedTime}s`);
  }
});

// Bei prefers-reduced-motion keine Animation abspielen, Ende direkt simulieren
if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
  modal.dispatchEvent(new AnimationEvent('animationend', {
    animationName: 'slideOut',
    elapsedTime: 0
  }));
}

Modal entfernt nach 0s

Test: Promise-Helfer für Animationsende prüfen

const waitForAnimation = (el, name) =>
  new Promise((resolve) => {
    const handler = (e) => {
      if (e.animationName !== name) return;
      el.removeEventListener('animationend', handler);
      resolve(e.elapsedTime);
    };
    el.addEventListener('animationend', handler);
  });

const box = document.createElement('div');
const pending = waitForAnimation(box, 'pulse');

// Ereignis im Test synthetisch auslösen
box.dispatchEvent(new AnimationEvent('animationend', {
  animationName: 'pulse',
  elapsedTime: 1.2
}));

const time = await pending;
console.log(`Animation beendet: ${time}s`);

Animation beendet: 1.2s

// Wichtig · Fallstricke

Keine echte Animation: Ein selbst erzeugtes AnimationEvent startet oder stoppt keine CSS-Animation – es informiert nur Listener. event.isTrusted ist false.
Einheit: elapsedTime wird in Sekunden angegeben, nicht in Millisekunden (anders als performance.now()).
Bubbling: Standardmäßig bubbles: false. Echte Animationsereignisse blubbern jedoch – für delegierte Listener daher bubbles: true setzen.
Nicht verwechseln mit AnimationPlaybackEvent der Web Animations API (element.animate()), das finish/cancel-Ereignisse beschreibt.
Kompatibilität: Der Konstruktor wird von allen aktuellen Browsern unterstützt; alte WebKit-Versionen nutzten Präfix-Ereignisse wie webkitAnimationEnd. animationcancel wird erst seit einigen Versionen breit unterstützt. In Node.js/jsdom ist AnimationEvent ggf. nicht vorhanden und muss per Polyfill bereitgestellt werden.

Siehe auch

AnimationEvent AnimationEvent.animationName AnimationEvent.elapsedTime AnimationEvent.pseudoElement EventTarget.dispatchEvent() TransitionEvent