Document.getAnimations() — Methode · JavaScript-Referenz

Signatur

Document.prototype.getAnimations()

Beschreibung

document.getAnimations() liefert eine Momentaufnahme aller Animationen im Dokument, die gerade laufen, pausiert sind oder noch starten sollen. Enthalten sind CSS-Animationen (CSSAnimation), CSS-Transitions (CSSTransition) und Animationen der Web Animations API, die per Element.animate() oder new Animation() erzeugt wurden. Auch Animationen auf Pseudo-Elementen wie ::before und ::after werden berücksichtigt.

Die Methode ist praktisch, wenn Sie alle Animationen einer Seite zentral steuern möchten. Typische Fälle: alles pausieren, wenn der Tab in den Hintergrund wechselt, Animationen für Nutzer mit prefers-reduced-motion sofort beenden, in Tests auf das Ende aller Animationen warten oder beim Debuggen nachsehen, welche Animationen gerade aktiv sind.

Das Array ist nicht live. Später gestartete Animationen tauchen darin nicht auf. Die Reihenfolge entspricht der Zusammensetzungsreihenfolge (composite order): zuerst CSS-Transitions, dann CSS-Animationen, danach Web-Animations, jeweils nach Erzeugungszeitpunkt beziehungsweise Baumreihenfolge. Nur Animationen der Standard-Zeitleiste des Dokuments und relevante Animationen werden aufgeführt. Abgeschlossene Animationen ohne fill-Modus fehlen.

Rückgabewert

Typ

Animation[]

Beschreibung

Ein neues, statisches Array von Animation-Objekten (bzw. deren Unterklassen CSSAnimation und CSSTransition), die aktuell relevant sind. Laufen keine Animationen, ist das Array leer.

Beispiele

Alle Animationen der Seite pausieren und fortsetzen

// Animationen stoppen, wenn der Tab unsichtbar wird
document.addEventListener('visibilitychange', () => {
  const animations = document.getAnimations();
  if (document.hidden) {
    animations.forEach((anim) => anim.pause());
  } else {
    animations.forEach((anim) => anim.play());
  }
  console.log(`${animations.length} Animation(en) umgeschaltet`);
});

3 Animation(en) umgeschaltet

Warten, bis alle Animationen beendet sind (z. B. in Tests)

const waitForAnimations = async () => {
  const animations = document.getAnimations();
  // finished ist ein Promise; abgebrochene Animationen lehnen es ab
  await Promise.allSettled(animations.map((anim) => anim.finished));
};

document.querySelector('.box').animate(
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 500 }
);

await waitForAnimations();
console.log('Alle Animationen abgeschlossen');

Alle Animationen abgeschlossen

Reduzierte Bewegung respektieren

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

if (reduceMotion.matches) {
  // Alle laufenden Animationen sofort an ihr Ende springen lassen
  document.getAnimations().forEach((anim) => anim.finish());
}

Animationen nach Typ auflisten (Debugging)

const summary = document.getAnimations().map((anim) => ({
  typ: anim.constructor.name,
  name: anim.animationName ?? anim.transitionProperty ?? anim.id ?? '(ohne Namen)',
  ziel: anim.effect?.target?.tagName,
  status: anim.playState
}));

console.table(summary);

┌─────────┬────────────────┬──────────┬────────┬───────────┐ │ (index) │ typ │ name │ ziel │ status │ │ 0 │ 'CSSTransition'│ 'opacity'│ 'DIV' │ 'running' │ │ 1 │ 'CSSAnimation' │ 'spin' │ 'SPAN' │ 'running' │ └─────────┴────────────────┴──────────┴────────┴───────────┘

// Wichtig · Fallstricke

Momentaufnahme: Das Array aktualisiert sich nicht selbst. Animationen, die nach dem Aufruf starten, müssen Sie mit einem erneuten Aufruf abfragen.
Style-Neuberechnung: Vor der Rückgabe werden ausstehende Stiländerungen angewendet, damit gerade gesetzte CSS-Animationen und -Transitions enthalten sind. In Schleifen oder pro Frame aufgerufen, kann das ein Layout/Style-Flush auslösen und Leistung kosten.
Shadow DOM: Animationen auf Elementen innerhalb von Shadow-Roots werden in Chromium und Firefox nicht über document.getAnimations() zurückgegeben. Nutzen Sie dafür shadowRoot.getAnimations() oder element.getAnimations({ subtree: true }).
iframes: Animationen in eingebetteten Dokumenten sind nicht enthalten. Jedes Dokument hat eine eigene Zeitleiste.
CSS-Animationen abbrechen: Ein cancel() auf einer CSSAnimation ist nur vorübergehend. Ändert sich der Stil erneut, kann der Browser die Animation neu erzeugen. Dauerhaft entfernen Sie sie über CSS, etwa mit animation: none.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Safari erst ab Version 14). Für ältere Umgebungen vorher prüfen, z. B. mit if ('getAnimations' in document).

Siehe auch

Element.animate() Animation Animation.finished Document.timeline Document.getSelection()