AnimationEvent.animation — Eigenschaft · JavaScript-Referenz

Signatur

AnimationEvent.animation

Beschreibung

Die schreibgeschützte Eigenschaft animation eines AnimationEvent verweist auf das Animationsobjekt, zu dem das Ereignis gehört. Bei CSS-Animationen ist das eine CSSAnimation-Instanz, also eine Unterklasse von Animation aus der Web Animations API.

Die Eigenschaft verbindet die CSS-Ereignisse animationstart, animationiteration, animationend und animationcancel mit der Web Animations API. Früher bekam man im Handler nur animationName, elapsedTime und pseudoElement. Wer die laufende Animation steuern wollte, musste sie erst über element.getAnimations() suchen. Über event.animation kann man die Animation direkt pausieren (pause()), das Tempo ändern (playbackRate), sie beenden (finish()), abbrechen (cancel()) oder ihren currentTime auslesen.

Das ist praktisch, wenn ein Element mehrere Animationen gleichzeitig hat oder dieselbe Keyframe-Regel auf mehrere Elemente wirkt. So ist eindeutig, welche Instanz das Ereignis ausgelöst hat.

Rückgabewert

Typ

CSSAnimation | Animation | null

Beschreibung

Das Animationsobjekt, das zum Ereignis gehört. Bei CSS-Animationen ist das normalerweise eine CSSAnimation-Instanz. Bei Ereignissen, die man selbst mit new AnimationEvent() erzeugt, kann der Wert null sein. In Browsern ohne Unterstützung ist er undefined.

Beispiele

Animation nach der ersten Wiederholung verlangsamen

// CSS: .spinner { animation: spin 1s linear infinite; }
const spinner = document.querySelector('.spinner');

spinner.addEventListener('animationiteration', (event) => {
  const anim = event.animation;
  if (!anim) return; // Eigenschaft wird nicht unterstützt

  console.log(anim.animationName, anim.playState);
  anim.playbackRate = 0.5; // halbe Geschwindigkeit
}, { once: true });

spin running

Fallback über getAnimations() bei fehlender Unterstützung

const getAnimationFromEvent = (event) => {
  if ('animation' in event && event.animation) {
    return event.animation;
  }
  // Fallback: passende CSSAnimation über den Namen suchen
  return event.target
    .getAnimations()
    .find((a) => a.animationName === event.animationName) ?? null;
};

const box = document.querySelector('.box');
box.addEventListener('animationstart', (event) => {
  const anim = getAnimationFromEvent(event);
  console.log('Gefunden:', anim?.animationName);
});

Gefunden: fade-in

Eine von mehreren parallelen Animationen gezielt pausieren

// CSS: .card { animation: pulse 2s infinite, slide 4s infinite; }
const card = document.querySelector('.card');

card.addEventListener('animationiteration', (event) => {
  if (event.animationName === 'pulse' && event.animation) {
    event.animation.pause(); // nur 'pulse' anhalten, 'slide' läuft weiter
    console.log('pulse pausiert bei', event.elapsedTime, 's');
  }
});

pulse pausiert bei 2 s

// Wichtig · Fallstricke

Kompatibilität: Die Eigenschaft ist neu und wird nicht in allen Browsern unterstützt. Prüfe vor dem Einsatz mit 'animation' in event und sieh eine Ersatzlösung über element.getAnimations() vor. Den aktuellen Stand der Unterstützung findest du auf MDN oder caniuse.com.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wie event.animation = … hat keine Wirkung. Die Eigenschaften und Methoden des zurückgegebenen Objekts lassen sich aber verändern bzw. aufrufen.
Nach animationend kann die Animation schon im Zustand finished sein. Wird die CSS-Eigenschaft animation entfernt oder geändert, verliert das Objekt seine Verbindung zum Element. Ruft man auf einem solchen Objekt play() auf, startet die Animation nicht zwingend so wie erwartet.
Wenn du die Wiedergabe über die Web Animations API steuerst (z. B. mit pause()), hat das Vorrang vor animation-play-state im CSS, bis sich die CSS-Deklaration wieder ändert.
Bei selbst erzeugten Ereignissen (new AnimationEvent('animationend')) ist keine echte Animation zugeordnet.

Siehe auch

AnimationEvent AnimationEvent.animationName AnimationEvent.elapsedTime AnimationEvent.pseudoElement CSSAnimation Animation Element.getAnimations()