Animation.commitStyles() — Methode · JavaScript-Referenz

Signatur

Animation.prototype.commitStyles()

Beschreibung

commitStyles() nimmt den aktuellen Zustand, den eine Animation auf ihr Zielelement anwendet, und überträgt die berechneten Werte der animierten Eigenschaften als Inline-Stile in das style-Attribut. So bleibt das Ergebnis einer Animation erhalten, nachdem sie beendet oder abgebrochen wurde.

Typischer Einsatz ist das Zusammenspiel mit fill: "forwards": Anstatt Animationen mit Füllmodus dauerhaft laufen zu lassen (was Speicher kostet und spätere Stiländerungen überdeckt), übernimmt man den Endzustand per commitStyles() und ruft danach cancel() auf. Das ist auch der empfohlene Weg im Zusammenhang mit dem automatischen Entfernen ersetzter Animationen (remove-Event, persist()).

Es werden nur die Eigenschaften geschrieben, die in den Keyframes der Animation vorkommen. Die Werte berücksichtigen den composite-Modus sowie darunterliegende Animationen im Effekt-Stapel. Die Methode wirkt nur auf Animationen mit einem KeyframeEffect und einem Zielelement, das ein style-Attribut besitzt.

Beispiele

Endzustand übernehmen und Animation freigeben

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

const anim = box.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 500, easing: 'ease-out', fill: 'forwards' }
);

await anim.finished;
// Endwert als Inline-Stil festschreiben …
anim.commitStyles();
// … und die Animation verwerfen, damit sie keine Ressourcen mehr bindet
anim.cancel();

console.log(box.style.transform);

translateX(300px)

Zwischenstand beim Abbrechen festhalten

const panel = document.querySelector('#panel');
const stopBtn = document.querySelector('#stop');

const anim = panel.animate(
  [{ opacity: 1 }, { opacity: 0 }],
  { duration: 3000, fill: 'both' }
);

stopBtn.addEventListener('click', () => {
  anim.pause();
  anim.commitStyles(); // aktuelle Deckkraft übernehmen
  anim.cancel();
  console.log('Deckkraft eingefroren bei', panel.style.opacity);
});

Deckkraft eingefroren bei 0.4213 (abhängig vom Klickzeitpunkt)

Mit dem remove-Event automatisch ersetzter Animationen

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

document.addEventListener('pointermove', (e) => {
  const anim = dot.animate(
    { transform: `translate(${e.clientX}px, ${e.clientY}px)` },
    { duration: 200, fill: 'forwards' }
  );
  // Wenn der Browser die überdeckte Animation entfernt,
  // Stil sichern, damit keine Sprünge entstehen
  anim.addEventListener('remove', () => anim.commitStyles());
});

// Wichtig · Fallstricke

Fehler bei nicht gerendertem Element: Ist das Zielelement nicht gerendert (z. B. display: none oder nicht im DOM), wirft die Methode eine InvalidStateError-DOMException. Ebenso wenn das Ziel kein style-Attribut unterstützt (z. B. Pseudo-Elemente).
Nach Ende ohne Füllmodus: Ist eine Animation ohne fill: "forwards" bereits beendet, wirkt sie nicht mehr – commitStyles() schreibt dann den Ausgangswert, nicht den Endwert. Daher vor dem Aufruf entweder fill setzen oder die Animation vorher pausieren.
Überschreibt Inline-Stile: Bereits vorhandene Inline-Werte der betroffenen Eigenschaften werden ersetzt; Inline-Stile haben hohe Spezifität und können spätere CSS-Klassen-Änderungen überdecken.
Geschrieben werden berechnete Werte (z. B. rgb(…) statt Farbnamen, px statt em).
Kompatibilität: in allen aktuellen Browsern verfügbar (Chrome/Edge 84+, Firefox 75+, Safari 13.1+).

Siehe auch

Animation Animation.persist() Animation.cancel() Animation.finished Element.animate() KeyframeEffect