</> programmierung.net
Start · Sprachen · JavaScript · Referenz · new KeyframeEffect()

new KeyframeEffect()

Methode

Erzeugt ein neues <code>KeyframeEffect</code>-Objekt (Ziel, Keyframes, Timing) für die Web Animations API oder klont einen vorhandenen Keyframe-Effekt.

seit JavaScript Web Animations API – Baseline: alle modernen Brows Kategorie: webapi

Signatur

new KeyframeEffect(target, keyframes, options) | new KeyframeEffect(sourceKeyframes)

Beschreibung

Der Konstruktor KeyframeEffect() erzeugt einen Animationseffekt, der beschreibt, was animiert wird (Zielelement und optional Pseudo-Element), wie es sich verändert (Keyframes) und mit welchem Timing das geschieht (Dauer, Verzögerung, Easing, Wiederholungen). Allein bewirkt der Effekt noch nichts: Erst wenn du ihn an ein Animation-Objekt übergibst und dieses abspielst, wird er sichtbar.

Im Unterschied zur Kurzform element.animate() trennst du hier Effekt und Wiedergabe. Das ist praktisch, wenn du Effekte vorab definieren, wiederverwenden, erst später einem Element zuweisen oder mit einer eigenen Zeitleiste (z. B. ScrollTimeline, DocumentTimeline mit Versatz) kombinieren möchtest.

Die zweite Form, new KeyframeEffect(sourceKeyframes), erstellt eine Kopie eines bestehenden Effekts mit denselben Keyframes, demselben Ziel und denselben Timing-Werten. Die Kopie ist unabhängig: Änderungen über setKeyframes() oder updateTiming() wirken sich nicht auf das Original aus.

Parameter

Name Typ Default Beschreibung
$target Pflicht Element | null Das zu animierende Element. null ist erlaubt – dann kann das Ziel später über die Eigenschaft target gesetzt werden.
$keyframes Pflicht Array<Object> | Object | null Keyframes entweder als Array von Objekten ([{ opacity: 0 }, { opacity: 1 }]) oder als Objekt mit Wert-Arrays ({ opacity: [0, 1] }). Eigenschaftsnamen in camelCase; offset, easing und composite pro Keyframe sind möglich.
$options number | Object 0 (Dauer) Entweder die Dauer in Millisekunden oder ein Objekt mit Timing-Angaben wie duration, delay, endDelay, easing, iterations, direction, fill, iterationStart sowie composite, iterationComposite und pseudoElement (z. B. '::before').
$sourceKeyframes KeyframeEffect Alternative Form mit nur einem Argument: ein vorhandener KeyframeEffect, der geklont werden soll.

Rückgabewert

Typ
KeyframeEffect
Beschreibung
Ein neues KeyframeEffect-Objekt, das mit new Animation(effect, timeline) abgespielt werden kann.

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

Effekt klonen und für ein anderes Element anpassen

const pulse = new KeyframeEffect(
  document.querySelector('#btn-a'),
  { transform: ['scale(1)', 'scale(1.1)', 'scale(1)'] },
  { duration: 600, iterations: Infinity }
);

// Kopie mit gleichen Keyframes und Timing
const pulseCopy = new KeyframeEffect(pulse);
pulseCopy.target = document.querySelector('#btn-b');
pulseCopy.updateTiming({ duration: 900 });

new Animation(pulse).play();
new Animation(pulseCopy).play();

console.log(pulse.getTiming().duration, pulseCopy.getTiming().duration);
600 900

Pseudo-Element animieren und Keyframes auslesen

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

const glow = new KeyframeEffect(
  card,
  [{ opacity: 0 }, { opacity: 0.8, offset: 0.3 }, { opacity: 0 }],
  { duration: 1200, pseudoElement: '::after' }
);

console.log(glow.getKeyframes().map((k) => k.computedOffset));
new Animation(glow).play();
[0, 0.3, 1]

// Wichtig · Fallstricke

  • Nur Effekt, keine Wiedergabe: Ein KeyframeEffect startet nicht von selbst. Du brauchst new Animation(effect, timeline) und play(). Wird die Zeitleiste weggelassen, nutzt Animation automatisch document.timeline.
  • Standarddauer 0: Ohne duration läuft die Animation sofort ab und ist praktisch unsichtbar.
  • Eigenschaftsnamen: CSS-Eigenschaften in camelCase schreiben (backgroundColor); float heißt cssFloat, offset als CSS-Eigenschaft heißt cssOffset, weil offset für die Keyframe-Position reserviert ist.
  • Fehler: Ungültige Keyframes (z. B. nicht aufsteigende offset-Werte) oder ungültiges easing lösen einen TypeError aus; ein ungültiger pseudoElement-Wert einen SyntaxError.
  • fill: 'forwards' hält den Endzustand fest, kann aber viele aktive Animationen anhäufen – besser am Ende per commitStyles() übernehmen und cancel() aufrufen.
  • Kompatibilität: Chrome/Edge 84+, Firefox 63+, Safari 13.1+. Die Option pseudoElement und composite werden erst in neueren Versionen unterstützt. Für sehr alte Browser gibt es das Polyfill web-animations-js.

Siehe auch

KeyframeEffect new Animation() Element.prototype.animate() KeyframeEffect.prototype.setKeyframes() KeyframeEffect.prototype.getKeyframes() AnimationEffect.prototype.updateTiming() Document.timeline
← Vorheriger Eintrag new KeyboardEvent()