Animation — Schnittstelle · JavaScript-Referenz

Signatur

interface Animation extends EventTarget

Beschreibung

Ein Animation-Objekt verbindet einen Effekt (meist einen KeyframeEffect, also Keyframes plus Timing auf einem Ziel-Element) mit einer Zeitleiste (standardmäßig document.timeline). Es steuert, wann und wie schnell der Effekt abläuft. Am häufigsten entsteht es als Rückgabewert von Element.animate(). Man kann es aber auch direkt mit new Animation(effect, timeline) erzeugen.

Wiedergabe-Methoden: play(), pause(), reverse(), finish(), cancel(), updatePlaybackRate(), persist() und commitStyles(). Wichtige Eigenschaften:

currentTime und startTime: aktuelle Position bzw. Startzeitpunkt auf der Zeitleiste, in Millisekunden. Beide lassen sich setzen, etwa zum Suchen (Seeking).
playbackRate: Abspieltempo. Negative Werte spielen rückwärts.
playState: einer der Werte "idle", "running", "paused" oder "finished". pending ist true, solange eine Wiedergabe-Änderung noch aussteht.
ready und finished: Promises für „bereit zum Abspielen“ und „fertig“.
effect, timeline, id und replaceState.

Außerdem feuert Animation die Events finish, cancel und remove. Man empfängt sie per addEventListener() oder über die Eigenschaften onfinish, oncancel und onremove. CSS-Animationen und CSS-Transitions sind ebenfalls Animation-Instanzen (CSSAnimation, CSSTransition). Man erreicht sie über element.getAnimations() oder document.getAnimations() und kann sie dann per Skript steuern.

Parameter

Name	Typ	Default	Beschreibung
$effect	AnimationEffect \| null	null	Konstruktor-Parameter: der abzuspielende Effekt, meist ein `KeyframeEffect`.
$timeline	AnimationTimeline \| null	document.timeline	Konstruktor-Parameter: die Zeitleiste, mit der die Animation verknüpft wird. Möglich sind z. B. `document.timeline`, eine `ScrollTimeline` oder `null` (dann gibt es keinen Zeitfortschritt).

Rückgabewert

Typ

Animation

Beschreibung

new Animation() liefert einen neuen Animations-Player im Zustand "idle". Er startet erst mit play().

Beispiele

Animation per Element.animate() erzeugen und steuern

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

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

console.log(anim instanceof Animation, anim.playState);

document.querySelector('#pause').addEventListener('click', () => anim.pause());
document.querySelector('#play').addEventListener('click', () => anim.play());
document.querySelector('#reverse').addEventListener('click', () => anim.reverse());

true "running"

Konstruktor mit KeyframeEffect und Ende per Promise abwarten

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

const effect = new KeyframeEffect(
  toast,
  [{ opacity: 0, transform: 'translateY(20px)' }, { opacity: 1, transform: 'none' }],
  { duration: 400, fill: 'both' }
);

const anim = new Animation(effect, document.timeline);
console.log(anim.playState); // vor play()

anim.play();
await anim.finished;
console.log('Einblenden fertig:', anim.playState);

"idle" Einblenden fertig: finished

Suchen (Seeking) mit einem Schieberegler und Tempo ändern

const spinner = document.querySelector('.spinner');
const slider = document.querySelector('#progress'); // <input type="range" max="2000">

const anim = spinner.animate(
  [{ transform: 'rotate(0turn)' }, { transform: 'rotate(1turn)' }],
  { duration: 2000, iterations: Infinity }
);
anim.pause();

slider.addEventListener('input', () => {
  anim.currentTime = Number(slider.value); // Millisekunden
});

// Tempo ohne Sprung verdoppeln
document.querySelector('#fast').addEventListener('click', () => {
  anim.updatePlaybackRate(2);
  anim.play();
});

finish-Event per addEventListener und onfinish, Endzustand festschreiben

const panel = document.querySelector('.panel');
const anim = panel.animate([{ height: '0px' }, { height: '200px' }], {
  duration: 300,
  fill: 'forwards'
});

const onDone = () => {
  anim.commitStyles(); // Endwerte ins style-Attribut schreiben
  anim.cancel();       // Effekt freigeben
  console.log(panel.style.height);
};
anim.addEventListener('finish', onDone, { once: true });

// Alternative über die Eigenschaft:
// anim.onfinish = onDone;

anim.addEventListener('cancel', () => console.log('abgebrochen'));

200px abgebrochen

// Wichtig · Fallstricke

Zeitangaben: currentTime und startTime sind in Millisekunden angegeben. Sie können null sein, z. B. im Zustand "idle" oder ohne aktive Zeitleiste. Bei Scroll-getriebenen Zeitleisten ist der Wert ein CSSNumericValue in Prozent.
finished-Promise: Ruft man cancel() auf, wird das aktuelle finished-Promise mit einem AbortError abgelehnt. Also await anim.finished in try/catch setzen. Nach jedem Neustart gibt es ein neues Promise-Objekt.
Tempo ändern: Wer playbackRate direkt setzt, erzeugt während der Wiedergabe einen Sprung. updatePlaybackRate() dagegen ändert das Tempo ohne Sprung und synchron zum nächsten Frame.
fill: "forwards" und Speicher: Animationen mit fill: "forwards" bleiben dauerhaft aktiv. Der Browser entfernt sie automatisch, sobald sie vollständig von anderen Animationen überdeckt werden (replaceState wird dann "removed", das Event remove feuert). Mit persist() lässt sich das verhindern. Besser ist meist commitStyles() gefolgt von cancel().
Leistung: Animationen von transform und opacity laufen im Compositor-Thread und damit flüssiger. Layout-Eigenschaften wie height oder width erzwingen dagegen ein Reflow in jedem Frame.
Barrierefreiheit: prefers-reduced-motion beachten, z. B. per matchMedia('(prefers-reduced-motion: reduce)').
Kompatibilität: Die Kern-API wird von Chrome, Edge, Firefox und Safari unterstützt (Safari ab 13.1, vollständig ab 14). commitStyles(), persist() und replaceState gibt es erst in neueren Versionen. ScrollTimeline und ViewTimeline fehlen in Firefox standardmäßig noch.

Siehe auch

Element.animate() KeyframeEffect AnimationEffect DocumentTimeline AnimationTimeline Element.getAnimations() Animation.finished Animation.prototype.play() AnimationPlaybackEvent