KeyframeEffect.composite — Eigenschaft · JavaScript-Referenz

Signatur

KeyframeEffect.composite

Beschreibung

Die Eigenschaft composite eines KeyframeEffect gibt die Kompositionsoperation an. Sie legt fest, wie die animierten Werte mit dem zugrunde liegenden Wert einer CSS-Eigenschaft verrechnet werden. Das ist entweder der statische Stilwert des Elements oder das Ergebnis einer Animation mit niedrigerer Priorität, die auf dieselbe Eigenschaft wirkt. Man kann den Wert lesen und schreiben. Neu gesetzte Werte gelten sofort, auch während die Animation läuft.

"replace" (Standard): Der animierte Wert ersetzt den zugrunde liegenden Wert vollständig.
"add": Der animierte Wert wird zum zugrunde liegenden Wert addiert. Bei transform werden die Funktionen aneinandergehängt, zum Beispiel translateX(50px) rotate(45deg).
"accumulate": Die Werte werden akkumuliert. Bei transform werden gleichartige Funktionen zusammengerechnet, zum Beispiel blur(2px) und blur(3px) zu blur(5px), statt sie hintereinander anzuwenden.

Die Eigenschaft hilft vor allem, wenn mehrere Animationen auf dieselbe Eigenschaft wirken. Ein Beispiel ist ein Hover-Effekt, der eine bestehende Transformation nicht überschreiben, sondern ergänzen soll. Mit "add" oder "accumulate" lassen sich Effekte stapeln, ohne dass man die Ausgangswerte im JavaScript kennen oder nachrechnen muss.

Man kann den Wert pro Effekt über composite setzen, bei der Erstellung über das Optionsobjekt von element.animate() bzw. new KeyframeEffect() übergeben oder in einzelnen Keyframes als composite angeben. Ein Wert in einem Keyframe hat für diesen Keyframe Vorrang vor dem Wert des Effekts.

Parameter

Name	Typ	Default	Beschreibung
$value	"replace" \| "add" \| "accumulate"	"replace"	Neuer Wert beim Schreiben der Eigenschaft. Ungültige Zeichenketten lösen einen `TypeError` aus.

Rückgabewert

Typ

"replace" | "add" | "accumulate"

Beschreibung

Die aktuelle Kompositionsoperation des Effekts als Zeichenkette.

Beispiele

Wert auslesen und nachträglich ändern

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

console.log(animation.effect.composite);

// Ab sofort auf die bestehende Transformation aufaddieren
animation.effect.composite = 'add';
console.log(animation.effect.composite);

replace add

Hover-Pulsieren, das eine vorhandene Drehung ergänzt

// CSS: .card { transform: rotate(-5deg); }
const card = document.querySelector('.card');

card.addEventListener('mouseenter', () => {
  card.animate(
    [{ transform: 'scale(1)' }, { transform: 'scale(1.1)' }, { transform: 'scale(1)' }],
    { duration: 400, composite: 'add' } // Drehung bleibt erhalten
  );
});

Unterschied zwischen add und accumulate

const el = document.querySelector('.foto');
el.style.filter = 'blur(2px)';

const effect = new KeyframeEffect(
  el,
  [{ filter: 'blur(3px)' }],
  { duration: 1000, fill: 'forwards' }
);
const anim = new Animation(effect, document.timeline);

effect.composite = 'add';        // Ergebnis: blur(2px) blur(3px)
// effect.composite = 'accumulate'; // Ergebnis: blur(5px)
anim.play();

anim.finished.then(() => {
  console.log(getComputedStyle(el).filter);
});

blur(2px) blur(3px)

Composite pro Keyframe überschreiben

const ball = document.querySelector('.ball');
const anim = ball.animate(
  [
    { transform: 'translateY(0)' },
    { transform: 'translateY(-100px)', composite: 'replace' },
    { transform: 'translateY(0)' }
  ],
  { duration: 800, composite: 'add' }
);

console.log(anim.effect.composite);
console.log(anim.effect.getKeyframes()[1].composite);

add replace

// Wichtig · Fallstricke

Browser-Kompatibilität: Firefox unterstützt die Eigenschaft seit Version 80, Safari seit 14 und Chrome/Edge vollständig erst seit 112. Ältere Chromium-Versionen ignorieren "add" und "accumulate" stillschweigend oder verarbeiten sie nur teilweise. Prüfen lässt sich die Unterstützung mit 'composite' in KeyframeEffect.prototype.
Nicht jede Eigenschaft ist additiv: Bei diskret animierten Eigenschaften wie display oder visibility verhalten sich "add" und "accumulate" wie "replace".
Die Reihenfolge zählt: Bei transform kommt es bei "add" auf die Reihenfolge der Funktionen an. So ergibt rotate() vor translate() ein anderes Bild als umgekehrt.
Abgrenzung zu verwandten Eigenschaften: iterationComposite steuert, wie sich Werte über Wiederholungen hinweg aufbauen. composite steuert die Verrechnung mit dem zugrunde liegenden Wert. Beides sind getrennte Einstellungen.
Stapeln mit fill: 'forwards': Jede neue additive Animation baut auf den vorherigen auf. Der Browser kann ersetzte Animationen automatisch entfernen (replaceState/persist()), dadurch können sich Endwerte unerwartet ändern.
Ungültige Werte lösen beim Setzen einen TypeError aus.

Siehe auch

Element.animate() Animation KeyframeEffect.iterationComposite KeyframeEffect.target KeyframeEffect.pseudoElement