Animation.effect — Eigenschaft · JavaScript-Referenz

Signatur

Animation.effect

Beschreibung

Die Eigenschaft effect eines Animation-Objekts verweist auf den Animationseffekt, der von dieser Animation abgespielt wird. In der Praxis ist das fast immer ein KeyframeEffect, der Zielelement, Keyframes und Timing-Optionen (Dauer, Easing, Iterationen usw.) bündelt. Die Animation selbst kümmert sich nur um die Wiedergabe: Abspielen, Pausieren, Geschwindigkeit, Zeitleiste.

Weil Effekt und Wiedergabe getrennt sind, kannst du den Effekt einer laufenden Animation zur Laufzeit austauschen, also etwa ein anderes Zielelement oder andere Keyframes zuweisen, ohne ein neues Animation-Objekt zu erstellen. Über animation.effect kommst du außerdem an Methoden wie getTiming(), updateTiming(), getComputedTiming() und bei KeyframeEffect auch an setKeyframes() und target.

Wird null zugewiesen, hat die Animation keinen Effekt mehr. Sie existiert weiter und kann abgespielt werden, verändert aber nichts sichtbar. Bei Animationen aus Element.animate() sowie bei CSS-Animationen und -Übergängen (CSSAnimation, CSSTransition) ist effect automatisch mit einem passenden KeyframeEffect belegt.

Parameter

Name	Typ	Default	Beschreibung
$value	AnimationEffect \| null		Beim Setzen: der neue Effekt (z. B. ein `KeyframeEffect`) oder `null`, um den Effekt zu entfernen.

Rückgabewert

Typ

AnimationEffect | null

Beschreibung

Der aktuell zugeordnete Effekt, meist ein KeyframeEffect, oder null, wenn kein Effekt gesetzt ist.

Beispiele

Effekt einer animate()-Animation auslesen

const box = document.querySelector('.box');
const anim = box.animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 800, easing: 'ease-out' }
);

const effect = anim.effect;
console.log(effect instanceof KeyframeEffect);
console.log(effect.target === box);
console.log(effect.getTiming().duration);

true true 800

Animation mit eigenem KeyframeEffect erstellen

const card = document.querySelector('.card');
const slideIn = new KeyframeEffect(
  card,
  [{ transform: 'translateX(-100%)' }, { transform: 'translateX(0)' }],
  { duration: 500, fill: 'forwards' }
);

const anim = new Animation(slideIn, document.timeline);
anim.play();
console.log(anim.effect === slideIn);

true

Effekt zur Laufzeit austauschen

const el = document.querySelector('#status');
const anim = el.animate(
  [{ color: 'gray' }, { color: 'black' }],
  { duration: 1000, iterations: Infinity }
);

// Bei einem Fehler auf eine rote Puls-Animation umschalten
const showError = () => {
  anim.effect = new KeyframeEffect(
    el,
    [{ color: 'red' }, { color: 'darkred' }],
    { duration: 400, iterations: Infinity, direction: 'alternate' }
  );
};

showError();
console.log(anim.effect.getTiming().duration);

400

Timing über effect nachträglich anpassen

const anim = document.body.animate(
  [{ backgroundColor: '#fff' }, { backgroundColor: '#eef' }],
  { duration: 2000 }
);

// Animation nachträglich verlangsamen und wiederholen
anim.effect.updateTiming({ duration: 4000, iterations: 3 });
const { duration, iterations } = anim.effect.getComputedTiming();
console.log(duration, iterations);

4000 3

// Wichtig · Fallstricke

Ein AnimationEffect kann immer nur zu einer Animation gehören. Weist du denselben Effekt einer zweiten Animation zu, wird er der ersten entzogen, und dort ist effect danach null.
Nach dem Austauschen des Effekts bleiben Wiedergabezustand und currentTime der Animation erhalten. Die neue Animation setzt also an der aktuellen Zeitposition an und beginnt nicht von vorn.
Setzt du effect = null, gilt die Animation bei einer currentTime jenseits von 0 sofort als beendet, weil die Effektdauer dann 0 ist. finished kann dann unerwartet früh erfüllt werden.
Bei CSS-Animationen (CSSAnimation) koppelt das Setzen eines eigenen Effekts die Animation von den Keyframes in der CSS-Datei ab. Spätere Änderungen an @keyframes wirken dann nicht mehr.
Browser-Unterstützung: Lesen wird überall unterstützt. Setzen und der Konstruktor new Animation() sind in Chrome/Edge 84+, Firefox 63+ und Safari 13.1+ verfügbar. In älteren Browsern ist ein Polyfill nötig (web-animations-js).

Siehe auch

Animation Element.animate() Animation.timeline Animation.id Animation.pending