CSSAnimation — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSAnimation extends Animation

Beschreibung

CSSAnimation ist eine Unterklasse von Animation aus der Web Animations API. Der Browser erzeugt für jede über die CSS-Eigenschaft animation-name gestartete Animation automatisch eine CSSAnimation-Instanz. Einen eigenen Konstruktor gibt es nicht: Man bekommt die Objekte über Element.getAnimations() oder document.getAnimations().

Zu allen geerbten Methoden und Eigenschaften (play(), pause(), reverse(), finish(), cancel(), currentTime, playbackRate, playState, finished, effect …) kommt nur eine eigene Eigenschaft hinzu:

animationName (nur lesbar, string): Name der zugehörigen @keyframes-Regel, also der Wert aus animation-name.

Die Schnittstelle bietet sich an, wenn Animationen deklarativ in CSS beschrieben sind und man sie trotzdem gezielt per Skript steuern will, z. B. anhalten, vorspulen, die Geschwindigkeit ändern oder auf das Ende warten (await animation.finished). So bleibt die Gestaltung im Stylesheet, und im JavaScript steckt nur die Steuerlogik.

Beispiele

CSS-Animationen eines Elements finden und benennen

// CSS:
// @keyframes pulse { from { opacity: 1 } to { opacity: .3 } }
// .badge { animation: pulse 1s infinite alternate; }

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

for (const anim of badge.getAnimations()) {
  if (anim instanceof CSSAnimation) {
    console.log(anim.animationName, anim.playState);
  }
}

pulse running

CSS-Animation per Button anhalten und fortsetzen

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

toggle.addEventListener('click', () => {
  const anim = spinner
    .getAnimations()
    .find((a) => a instanceof CSSAnimation && a.animationName === 'spin');
  if (!anim) return;

  anim.playState === 'running' ? anim.pause() : anim.play();
  toggle.textContent = anim.playState === 'running' ? 'Pause' : 'Weiter';
});

Auf das Ende einer CSS-Einblendung warten

const dialog = document.querySelector('.dialog');
dialog.classList.add('fade-in'); // startet @keyframes fadeIn

const waitForCssAnimation = async (el, name) => {
  const anim = el
    .getAnimations()
    .find((a) => a instanceof CSSAnimation && a.animationName === name);
  if (anim) await anim.finished;
};

await waitForCssAnimation(dialog, 'fadeIn');
dialog.querySelector('input')?.focus();
console.log('Einblendung fertig');

Einblendung fertig

Alle CSS-Animationen der Seite verlangsamen

// z. B. als Debug-Hilfe: alles in halber Geschwindigkeit
document
  .getAnimations()
  .filter((a) => a instanceof CSSAnimation)
  .forEach((a) => {
    a.playbackRate = 0.5;
  });

console.log(document.getAnimations().length, 'Animationen angepasst');

3 Animationen angepasst

// Wichtig · Fallstricke

Kein Konstruktor: new CSSAnimation() wirft einen TypeError. Eigene Animationen legt man mit element.animate() oder new Animation() an.
Kopplung an CSS: Entfernt man animation-name oder die Klasse, wird die Animation abgebrochen und das Objekt ist nutzlos. Ändert sich animation-name, entsteht eine neue Instanz. Referenzen also nicht dauerhaft zwischenspeichern.
Skript schlägt CSS: Nach einem Aufruf von pause() oder play() per Skript werden spätere Änderungen an animation-play-state im CSS für diese Animation ignoriert. Dasselbe gilt für andere Eigenschaften, die man über effect.updateTiming() überschrieben hat.
Zeitpunkt: Direkt nachdem eine Klasse gesetzt wurde, muss der Stil erst berechnet werden. getAnimations() erzwingt diese Stilberechnung, das kann bei häufigen Aufrufen auf die Leistung gehen.
Pseudo-Elemente: Animationen auf ::before/::after findet man mit getAnimations({ subtree: true }). effect.target zeigt dann auf das Elternelement, das Pseudo-Element steht in effect.pseudoElement.
Kompatibilität: Wird seit 2020 von allen aktuellen Browsern unterstützt. Für ältere Browser vorher per 'CSSAnimation' in window prüfen.
Für CSS-Übergänge (transition) gibt es die Schwesterklasse CSSTransition mit der Eigenschaft transitionProperty.

Siehe auch

Animation Element.prototype.animate() CSSTransition Navigation CSSMathMin