Element.getAnimations() — Methode · JavaScript-Referenz

Signatur

Element.prototype.getAnimations(options)

Beschreibung

getAnimations() liefert alle aktuell relevanten Animationen eines Elements. Dazu gehören laufende, pausierte und noch ausstehende Animationen, also solche mit einer Verzögerung (delay), die noch nicht begonnen haben. Erfasst werden gleichermaßen CSS-Animationen (CSSAnimation), CSS-Transitions (CSSTransition) und per Element.animate() erzeugte Animationen. Abgeschlossene Animationen ohne fill-Modus sind nicht mehr enthalten.

Die Methode eignet sich, um Animationen zentral zu steuern, ohne Referenzen selbst speichern zu müssen. Damit lassen sich zum Beispiel alle Animationen eines Elements pausieren, abbrechen oder beschleunigen. Man kann auch über Promise.all() auf das Ende aller Animationen warten, bevor ein Element aus dem DOM entfernt wird.

Mit der Option { subtree: true } werden zusätzlich die Animationen aller Nachfahren zurückgegeben, einschließlich der Pseudo-Elemente ::before und ::after. Die Reihenfolge des Arrays entspricht der Zusammensetzungsreihenfolge (Composite Order): Zuerst kommen CSS-Transitions, dann CSS-Animationen, danach Script-Animationen in der Reihenfolge ihrer Erstellung.

Vor dem Ermitteln der Ergebnisse aktualisiert der Browser ausstehende Stiländerungen. Ein Aufruf kann deshalb einen Style-Recalc erzwingen.

Rückgabewert

Typ

Animation[]

Beschreibung

Ein neues, nicht live aktualisiertes Array von Animation-Objekten (bzw. CSSAnimation/CSSTransition). Das Array ist leer, wenn keine relevanten Animationen existieren.

Beispiele

Alle Animationen eines Elements pausieren und fortsetzen

const box = document.querySelector('.box');
box.animate([{ transform: 'rotate(0)' }, { transform: 'rotate(360deg)' }], { duration: 2000, iterations: Infinity });

const toggle = () => {
  for (const anim of box.getAnimations()) {
    anim.playState === 'running' ? anim.pause() : anim.play();
  }
};

document.querySelector('#toggle').addEventListener('click', toggle);
console.log(box.getAnimations().length);

1

Auf das Ende aller Animationen warten, bevor ein Element entfernt wird

const removeWithFade = async (el) => {
  el.classList.add('fade-out'); // CSS-Transition oder -Animation auslösen
  await Promise.all(el.getAnimations({ subtree: true }).map((a) => a.finished));
  el.remove();
  console.log('Element entfernt');
};

removeWithFade(document.querySelector('.toast'));

Element entfernt

Animationstypen unterscheiden und alle Animationen beschleunigen

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

for (const anim of card.getAnimations()) {
  if (anim instanceof CSSAnimation) {
    console.log('CSS-Animation:', anim.animationName);
  } else if (anim instanceof CSSTransition) {
    console.log('Transition:', anim.transitionProperty);
  } else {
    console.log('Web-Animation:', anim.id || '(ohne id)');
  }
  anim.updatePlaybackRate(2); // doppelte Geschwindigkeit, ohne Sprung
}

CSS-Animation: pulse Transition: opacity

Respektvoll mit prefers-reduced-motion umgehen

const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');

if (reduce.matches) {
  document.documentElement
    .getAnimations({ subtree: true })
    .forEach((anim) => anim.finish());
}

// Wichtig · Fallstricke

Kein Live-Array: Das Ergebnis ist eine Momentaufnahme. Später gestartete Animationen tauchen darin nicht auf, deshalb muss die Methode erneut aufgerufen werden.
Endlose Animationen: Bei iterations: Infinity bzw. animation-iteration-count: infinite wird das Promise finished nie erfüllt. Ein Promise.all() darüber bleibt dann für immer hängen.
Abbruch: Wird eine Animation mit cancel() abgebrochen oder eine CSS-Klasse entfernt, wird finished mit einem AbortError abgelehnt. Fange das mit try/catch ab oder verwende Promise.allSettled().
CSS-Transitions erscheinen erst nach einem Stilwechsel: Direkt nach dem Setzen einer Klasse erzwingt getAnimations() selbst den Style-Recalc. Die Transition ist also sofort enthalten, das kostet allerdings Performance, besonders mit subtree: true auf großen Bäumen.
Animationen mit fill: 'forwards' bleiben nach ihrem Ende enthalten, solange sie nicht automatisch ersetzt werden (Stichwort replaceState/persist()).
Kompatibilität: Die Methode ist seit 2020 in allen modernen Browsern verfügbar, die Option subtree wird dort ebenfalls unterstützt. Alte Browser wie der Internet Explorer oder Safari vor Version 13.1/14 bieten sie nicht an. Prüfe die Unterstützung mit 'getAnimations' in Element.prototype. Für das gesamte Dokument gibt es document.getAnimations().

Siehe auch

Element.animate() Document.getAnimations() Animation Animation.finished Element.getAttributeNS()