KeyframeEffect.setKeyframes() — Methode · JavaScript-Referenz

Signatur

KeyframeEffect.prototype.setKeyframes(keyframes)

Beschreibung

Die Methode setKeyframes() gehört zur KeyframeEffect-Schnittstelle der Web Animations API. Sie tauscht die komplette Keyframe-Liste eines Effekts aus. Zeitsteuerung (Dauer, Verzögerung, Easing), Wiedergabestatus und aktuelle Position der zugehörigen Animation bleiben dabei erhalten. Die neuen Keyframes wirken sich sofort auf die laufende Darstellung aus.

Das ist praktisch, wenn sich das Animationsziel zur Laufzeit ändert, zum Beispiel wenn ein Element einer neuen Mauszeiger-Position folgen soll oder ein Farbschema umgeschaltet wird. Anstatt die alte Animation abzubrechen und mit element.animate() eine neue zu starten, änderst du nur den Inhalt des Effekts. Das spart Aufwand und verhindert sichtbare Sprünge.

Wie bei element.animate() und dem Konstruktor new KeyframeEffect() gibt es zwei Formate für Keyframes: ein Array von Keyframe-Objekten, etwa [{ opacity: 0 }, { opacity: 1 }], oder ein Objekt mit Eigenschafts-Arrays, etwa { opacity: [0, 1] }. Übergibst du null, wird die Keyframe-Liste geleert und der Effekt hat keine sichtbare Wirkung mehr.

Parameter

Name	Typ	Default	Beschreibung
$keyframes Pflicht	Array<Object> \| Object \| null		Die neuen Keyframes. Entweder ein Array von Keyframe-Objekten (optional mit `offset`, `easing` und `composite`) oder ein Objekt, dessen Eigenschaften Arrays von Werten enthalten. Bei `null` wird die Liste geleert.

Rückgabewert

Typ

undefined

Beschreibung

Die Methode gibt nichts zurück. Die Änderung wird direkt am Effekt vorgenommen.

Beispiele

Keyframes einer laufenden Animation austauschen

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

const animation = box.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }],
  { duration: 2000, iterations: Infinity, direction: 'alternate' }
);

// Nach 3 Sekunden statt der Verschiebung eine Drehung abspielen
setTimeout(() => {
  animation.effect.setKeyframes([
    { transform: 'rotate(0deg)' },
    { transform: 'rotate(360deg)' }
  ]);
  console.log(animation.effect.getKeyframes().length);
}, 3000);

2

Objekt-Format mit Eigenschafts-Arrays verwenden

const effect = new KeyframeEffect(
  document.querySelector('#hinweis'),
  { opacity: [0, 1] },
  { duration: 500, fill: 'forwards' }
);

// Farbe und Deckkraft gleichzeitig animieren
effect.setKeyframes({
  opacity: [0, 1],
  backgroundColor: ['#fff', '#ffe08a', '#fff']
});

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

console.log(effect.getKeyframes().map(k => k.computedOffset));

[0, 0.5, 1]

Element dynamisch dem Mauszeiger folgen lassen

const dot = document.querySelector('.dot');
const anim = dot.animate(
  [{ transform: 'translate(0, 0)' }],
  { duration: 400, fill: 'forwards', easing: 'ease-out' }
);

document.addEventListener('click', (event) => {
  const current = getComputedStyle(dot).transform;
  // Neuer Start ist die aktuelle Position, neues Ziel der Klickpunkt
  anim.effect.setKeyframes([
    { transform: current === 'none' ? 'translate(0, 0)' : current },
    { transform: `translate(${event.clientX}px, ${event.clientY}px)` }
  ]);
  anim.currentTime = 0;
  anim.play();
});

// Wichtig · Fallstricke

Fehler: Ungültige Keyframes führen zu einem TypeError, zum Beispiel wenn die Offsets nicht aufsteigend sortiert sind, außerhalb von 0–1 liegen oder ein easing-Wert nicht geparst werden kann. In diesem Fall bleiben die alten Keyframes unverändert.
Nicht animierbare Eigenschaften wie display (in älteren Browsern) werden stillschweigend ignoriert. Eigenschaftsnamen müssen in camelCase geschrieben werden (backgroundColor). Ausnahme ist cssFloat für float.
Aktueller Zustand: Die Wiedergabeposition wird nicht zurückgesetzt. Wer die Animation neu starten will, muss animation.currentTime = 0 selbst setzen.
Bei CSSAnimation-Objekten (aus CSS-@keyframes) entkoppelt setKeyframes() die Animation dauerhaft von späteren Änderungen der @keyframes-Regel.
Kompatibilität: Wird in Chrome/Edge 84+, Firefox 63+ und Safari 13.1+ unterstützt. Für sehr alte Browser gibt es das Polyfill web-animations-js.

Siehe auch

Element.animate() Animation Animation.effect KeyframeEffect.getKeyframes() Performance.getEntries()