KeyframeEffect — Schnittstelle · JavaScript-Referenz

Signatur

interface KeyframeEffect extends AnimationEffect

Beschreibung

KeyframeEffect ist der Baustein der Web Animations API, der festlegt, was animiert wird: ein Zielelement (target), eine Liste von Keyframes und Zeitangaben wie Dauer, Verzögerung oder Wiederholungen. Abgespielt wird der Effekt erst, wenn du ihn an ein Animation-Objekt übergibst: new Animation(effect, document.timeline).

Intern nutzt Element.prototype.animate() genau diese Schnittstelle: Die Methode baut einen KeyframeEffect, legt eine Animation an und startet sie. Selbst einen KeyframeEffect zu bauen lohnt sich, wenn du einen Effekt wiederverwenden, vor dem Start ändern, zwischen Elementen austauschen oder mit GroupEffect-ähnlichen Mustern selbst koordinieren willst.

Wichtige Mitglieder:

target: das animierte Element (oder null), lesbar und schreibbar.
pseudoElement: ein Pseudo-Element wie "::before" als Ziel.
composite: wie die Werte mit darunterliegenden Werten kombiniert werden ("replace", "add", "accumulate").
iterationComposite: wie sich die Werte über Wiederholungen hinweg aufbauen ("replace" | "accumulate").
getKeyframes() / setKeyframes(): berechnete Keyframes auslesen oder ersetzen.
Geerbt von AnimationEffect: getTiming(), getComputedTiming(), updateTiming().

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	Element \| null		Das Element, das animiert werden soll. `null` ist erlaubt, dann wird nichts sichtbar gerendert.
$keyframes Pflicht	Keyframe[] \| PropertyIndexedKeyframes \| null		Keyframes als Array von Objekten (`[{ opacity: 0 }, { opacity: 1 }]`) oder als Objekt, das jeder Eigenschaft ein Werte-Array zuordnet (`{ opacity: [0, 1] }`). Pro Keyframe sind `offset`, `easing` und `composite` erlaubt.
$options	number \| KeyframeEffectOptions	0	Dauer in Millisekunden oder ein Objekt mit `duration`, `delay`, `endDelay`, `iterations`, `iterationStart`, `direction`, `easing`, `fill`, `composite`, `iterationComposite` und `pseudoElement`.
$source	KeyframeEffect		Alternative Konstruktorform `new KeyframeEffect(source)`: Erstellt eine unabhängige Kopie eines bestehenden Effekts.

Rückgabewert

Typ

KeyframeEffect

Beschreibung

Ein neuer Effekt, der noch nicht abgespielt wird. Zum Abspielen übergibst du ihn an new Animation() oder weist ihn animation.effect zu.

Beispiele

Effekt erstellen und mit Animation abspielen

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

const fadeIn = new KeyframeEffect(
  box,
  [
    { opacity: 0, transform: 'translateY(20px)' },
    { opacity: 1, transform: 'translateY(0)' }
  ],
  { duration: 400, easing: 'ease-out', fill: 'forwards' }
);

const animation = new Animation(fadeIn, document.timeline);
animation.play();

await animation.finished;
console.log('Einblenden fertig');

Einblenden fertig

Keyframes auslesen und nachträglich ändern

const effect = new KeyframeEffect(
  document.querySelector('#banner'),
  { backgroundColor: ['#fff', '#ffeb3b'] },
  1000
);

console.log(effect.getKeyframes().length);

// Farbe zur Laufzeit austauschen
effect.setKeyframes({ backgroundColor: ['#fff', '#4caf50'] });
effect.updateTiming({ iterations: 2, direction: 'alternate' });

console.log(effect.getTiming().iterations);
new Animation(effect).play();

2 2

Effekt kopieren und auf mehrere Elemente anwenden

const template = new KeyframeEffect(
  null,
  [{ transform: 'scale(1)' }, { transform: 'scale(1.1)' }, { transform: 'scale(1)' }],
  { duration: 300 }
);

document.querySelectorAll('.card').forEach((card, i) => {
  const effect = new KeyframeEffect(template); // unabhängige Kopie
  effect.target = card;
  effect.updateTiming({ delay: i * 100 });
  new Animation(effect).play();
});

Pseudo-Element animieren

const pulse = new KeyframeEffect(
  document.querySelector('.badge'),
  { opacity: [1, 0.3, 1] },
  { duration: 1200, iterations: Infinity, pseudoElement: '::after' }
);

const anim = new Animation(pulse);
anim.play();
console.log(pulse.pseudoElement);

::after

// Wichtig · Fallstricke

Ein Effekt spielt nichts von allein ab: Ohne Animation-Objekt und play() passiert nichts. Für einfache Fälle reicht element.animate().
Standardwert für fill ist "none": Nach dem Ende springt das Element auf seinen Ausgangsstil zurück. fill: "forwards" hält den Endzustand, erzeugt aber dauerhaft aktive Animationen. Besser ist oft, den Endwert per commitStyles() zu übernehmen und dann cancel() aufzurufen.
Die Standarddauer ist 0: Ohne duration läuft die Animation sofort durch.
Eigenschaftsnamen schreibst du in camelCase (backgroundColor), float wird zu cssFloat und offset zu cssOffset. Ungültige easing-Werte lösen einen TypeError aus.
Uneinheitliche Keyframe-Abstände (offset) müssen aufsteigend sortiert sein, sonst gibt es einen TypeError.
Leistung: Nur transform und opacity laufen zuverlässig auf dem Compositor-Thread. Andere Eigenschaften wie width oder top lösen ein neues Layout aus.
Kompatibilität: Konstruktor, getKeyframes() und setKeyframes() funktionieren in Chrome/Edge 84+, Firefox 63+ und Safari 13.1+. pseudoElement und composite gibt es erst in neueren Versionen. iterationComposite wird nur teilweise unterstützt.
Denke an Barrierefreiheit: Mit matchMedia('(prefers-reduced-motion: reduce)') kannst du Animationen abschwächen.

Siehe auch

Animation Element.prototype.animate() KeyboardEvent CSSKeyframeRule MessageEvent