CSSAnimation.animationName — Eigenschaft · JavaScript-Referenz

Signatur

CSSAnimation.animationName

Beschreibung

Die Eigenschaft animationName des Interfaces CSSAnimation liefert den Wert aus der CSS-Eigenschaft animation-name, also den Bezeichner der @keyframes-Regel, die die Animation steuert. CSSAnimation erweitert Animation: Jede per CSS deklarierte Animation taucht über die Web Animations API als CSSAnimation-Objekt auf.

Nützlich ist das, wenn du laufende Animationen per element.getAnimations() oder document.getAnimations() abfragst und eine bestimmte Animation herausfiltern willst, um sie zu pausieren, zu beschleunigen, zurückzuspulen oder auf ihr Ende (finished) zu warten.

Die Eigenschaft ist schreibgeschützt. Wenn du den Namen ändern willst, musst du die CSS-Eigenschaft animation-name am Element ändern. Der Browser erzeugt dann ein neues CSSAnimation-Objekt.

Rückgabewert

Typ

string

Beschreibung

Der Name der @keyframes-Regel, z. B. "fade-in". Das ist nicht das Gleiche wie Animation.id.

Beispiele

Namen aller CSS-Animationen eines Elements ausgeben

// CSS: .box { animation: fade-in 1s, slide 2s infinite; }
const box = document.querySelector('.box');

const names = box.getAnimations()
  .filter((anim) => anim instanceof CSSAnimation)
  .map((anim) => anim.animationName);

console.log(names);

["fade-in", "slide"]

Bestimmte Animation gezielt pausieren

// CSS: .spinner { animation: spin 1s linear infinite; }
const spinner = document.querySelector('.spinner');

const pauseAnimation = (el, name) => {
  const anim = el.getAnimations()
    .find((a) => a instanceof CSSAnimation && a.animationName === name);
  anim?.pause();
  return anim?.playState;
};

console.log(pauseAnimation(spinner, 'spin'));

paused

Auf das Ende einer Einblend-Animation warten

// CSS: .modal.open { animation: modal-in 300ms ease-out; }
const modal = document.querySelector('.modal');
modal.classList.add('open');

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

await waitForAnimation(modal, 'modal-in');
console.log('Modal vollständig eingeblendet');

Modal vollständig eingeblendet

Seitenweit alle Animationen mit einem Namen beschleunigen

document.getAnimations()
  .filter((a) => a.animationName === 'pulse')
  .forEach((a) => a.updatePlaybackRate(2));

console.log('pulse läuft jetzt doppelt so schnell');

pulse läuft jetzt doppelt so schnell

// Wichtig · Fallstricke

Nur für CSS-Animationen: Animationen, die mit element.animate() erzeugt wurden, sind normale Animation-Objekte ohne animationName. Der Wert ist dort undefined. CSS-Transitions sind CSSTransition-Objekte und haben stattdessen transitionProperty. Prüfe den Typ bei Bedarf mit instanceof CSSAnimation.
Schreibgeschützt: Eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen TypeError.
Groß-/Kleinschreibung: Bezeichner in @keyframes unterscheiden Groß- und Kleinbuchstaben. Vergleiche deshalb exakt.
getAnimations() liefert nur laufende oder ausstehende Animationen. Mit animation-name: none oder nach dem Ende ohne fill-mode wird die Animation nicht mehr aufgeführt.
Das CSSAnimation-Objekt wird ersetzt, sobald sich animation-name ändert. Referenzen auf das alte Objekt veralten dann.
Browser-Unterstützung: Seit 2020 in allen modernen Browsern vorhanden, nicht im Internet Explorer.

Siehe auch

Animation Animation.finished CSSPrimitiveValue.primitiveType AnimationEvent.animationName Animation.timeline