KeyframeEffect.iterationComposite — Eigenschaft · JavaScript-Referenz

Signatur

KeyframeEffect.iterationComposite

Beschreibung

Die Eigenschaft iterationComposite eines KeyframeEffect bestimmt, was mit den animierten Werten passiert, wenn eine Animation mehrfach durchläuft (iterations > 1). Sie ist lesbar und schreibbar und nimmt einen der beiden Zeichenketten-Werte "replace" oder "accumulate" an.

"replace" (Standard): Jede Iteration startet wieder bei den Werten des ersten Keyframes. Eine Bewegung von 0px nach 100px springt also nach jedem Durchlauf zurück.
"accumulate": Der Endwert der vorherigen Iteration wird zu den Werten der nächsten addiert. Aus translateX(0) → translateX(100px) wird in der zweiten Iteration 100px → 200px, in der dritten 200px → 300px usw.

Das ist nützlich für fortlaufende Bewegungen wie ein „Schritt für Schritt“ wanderndes Element, eine sich stetig weiterdrehende Rotation oder schrittweise wachsende Werte, ohne dafür riesige Keyframe-Listen oder JavaScript-Schleifen zu schreiben.

Der Wert kann beim Erzeugen über das Optionsobjekt von new KeyframeEffect() bzw. Element.animate() gesetzt oder später direkt über die Eigenschaft geändert werden. Nicht zu verwechseln mit composite, das regelt, wie sich der Effekt mit anderen Animationen bzw. dem Grundwert der Eigenschaft kombiniert.

Parameter

Name	Typ	Default	Beschreibung
$value	"replace" \| "accumulate"	"replace"	Neuer Wert beim Setzen der Eigenschaft. `"replace"` setzt jede Iteration zurück, `"accumulate"` baut auf dem Ergebnis der vorherigen Iteration auf. Ungültige Werte lösen einen `TypeError` aus.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Modus als "replace" oder "accumulate". In Browsern ohne Unterstützung ist die Eigenschaft undefined.

Beispiele

Element wandert mit jeder Iteration weiter

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

const effect = new KeyframeEffect(
  box,
  [
    { transform: 'translateX(0)' },
    { transform: 'translateX(100px)' }
  ],
  {
    duration: 1000,
    iterations: 3,
    fill: 'forwards',
    iterationComposite: 'accumulate'
  }
);

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

console.log(effect.iterationComposite);

accumulate // Box bewegt sich 0→100px, 100→200px, 200→300px

Modus zur Laufzeit umschalten

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

const animation = spinner.animate(
  [{ transform: 'rotate(0deg)' }, { transform: 'rotate(90deg)' }],
  { duration: 500, iterations: 8 }
);

const effect = animation.effect;
console.log(effect.iterationComposite); // Standardwert

// Statt zurückzuspringen um jeweils weitere 90° drehen
effect.iterationComposite = 'accumulate';
console.log(effect.iterationComposite);

replace accumulate

Feature-Erkennung mit Fallback

const supportsIterationComposite =
  typeof KeyframeEffect !== 'undefined' &&
  'iterationComposite' in KeyframeEffect.prototype;

const el = document.querySelector('.step');
const iterations = 4;

if (supportsIterationComposite) {
  el.animate(
    [{ transform: 'translateY(0)' }, { transform: 'translateY(50px)' }],
    { duration: 400, iterations, fill: 'forwards', iterationComposite: 'accumulate' }
  );
} else {
  // Fallback: Endwert direkt in die Keyframes schreiben
  el.animate(
    [{ transform: 'translateY(0)' }, { transform: `translateY(${50 * iterations}px)` }],
    { duration: 400 * iterations, fill: 'forwards', easing: 'steps(4, end)' }
  );
}

console.log('Unterstützt:', supportsIterationComposite);

Unterstützt: true // in Firefox, sonst false

// Wichtig · Fallstricke

Browser-Kompatibilität: iterationComposite stammt aus der Spezifikation Web Animations Level 2 und gilt als experimentell. Derzeit unterstützt nur Firefox (ab Version 80) die Eigenschaft. Chromium-Browser und Safari ignorieren die Option im Optionsobjekt stillschweigend, deshalb ist eine Feature-Erkennung ('iterationComposite' in KeyframeEffect.prototype) sinnvoll.

Die Eigenschaft wirkt sich nur bei iterations > 1 sichtbar aus.
Nicht jede CSS-Eigenschaft lässt sich sinnvoll kumulieren. Diskrete Werte wie display oder visibility werden nicht addiert, sondern verhalten sich wie bei "replace".
Wie addiert wird, hängt vom Typ ab: Bei transform-Listen werden Funktionen gleichen Typs addiert (z. B. Winkel bei rotate()), Farben werden komponentenweise summiert und dabei gegebenenfalls begrenzt.
Ohne fill: 'forwards' springt das Element nach Ende der letzten Iteration auf seinen Ausgangswert zurück, auch wenn es vorher weitergewandert ist.
Nicht mit KeyframeEffect.composite verwechseln: Dort geht es darum, wie sich der Effekt mit anderen Animationen bzw. dem Grundwert kombiniert, nicht zwischen Iterationen.

Siehe auch

KeyframeEffect KeyframeEffect.composite Element.prototype.animate() Animation AnimationEffect.prototype.getTiming() PerformanceTiming.domComplete