new Animation() — Methode · JavaScript-Referenz

Signatur

new Animation(effect, timeline)

Beschreibung

Mit new Animation() erstellt man ein Animation-Objekt, das einen Animationseffekt (meist ein KeyframeEffect) mit einer Zeitachse (AnimationTimeline) verbindet. Im Unterschied zur Kurzform Element.animate() startet eine so erzeugte Animation nicht automatisch. Sie bleibt im Zustand "idle", bis man play() aufruft.

Der Konstruktor lohnt sich, wenn man Effekt und Wiedergabe getrennt verwalten will. Typische Fälle: einen KeyframeEffect vorab definieren und mehrfach verwenden, eine Animation vor dem Start konfigurieren (z. B. playbackRate, currentTime, onfinish) oder eine eigene Zeitachse wie eine DocumentTimeline mit Versatz bzw. eine ScrollTimeline anhängen.

Lässt man timeline weg (undefined), wird document.timeline verwendet. Übergibt man ausdrücklich null, hat die Animation keine Zeitachse und läuft erst, wenn man später eine zuweist oder currentTime von Hand setzt.

Parameter

Name	Typ	Default	Beschreibung
$effect	AnimationEffect \| null	null	Der abzuspielende Effekt, meist ein `KeyframeEffect`. Kann später über `animation.effect` gesetzt oder ausgetauscht werden.
$timeline	AnimationTimeline \| null	document.timeline	Die Zeitachse, an die die Animation gebunden wird, z. B. `document.timeline`, eine eigene `DocumentTimeline` oder eine `ScrollTimeline`. Bei `null` hat die Animation keine Zeitachse.

Rückgabewert

Typ

Animation

Beschreibung

Eine neue Animation-Instanz im Zustand playState === "idle", die noch nicht abgespielt wird.

Beispiele

Animation aus einem KeyframeEffect erzeugen und starten

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

const effect = new KeyframeEffect(
  box,
  [
    { transform: 'translateX(0)', opacity: 1 },
    { transform: 'translateX(300px)', opacity: 0.3 }
  ],
  { duration: 1000, easing: 'ease-in-out', fill: 'forwards' }
);

const animation = new Animation(effect, document.timeline);
console.log(animation.playState);

animation.play();
console.log(animation.playState);

idle running

Vor dem Start konfigurieren und auf das Ende warten

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

const fadeOut = new Animation(
  new KeyframeEffect(toast, [{ opacity: 1 }, { opacity: 0 }], { duration: 600, fill: 'forwards' })
);

fadeOut.playbackRate = 2; // doppelt so schnell

const hideToast = async () => {
  fadeOut.play();
  await fadeOut.finished;
  toast.hidden = true;
  console.log('Toast ausgeblendet');
};

hideToast();

Toast ausgeblendet

Eigene Zeitachse mit Versatz und manuelle Steuerung

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

// Zeitachse, die 500 ms nach der Dokument-Zeitachse startet
const timeline = new DocumentTimeline({ originTime: 500 });
const spin = new Animation(effect, timeline);
spin.play();

// Ohne Zeitachse: Fortschritt von Hand setzen (z. B. per Schieberegler)
const scrub = new Animation(effect.clone?.() ?? effect, null);
scrub.pause();
scrub.currentTime = 1000; // Hälfte der Drehung
console.log(scrub.currentTime);

1000

// Wichtig · Fallstricke

Startet nicht automatisch: Anders als bei Element.animate() muss man play() selbst aufrufen. Ohne diesen Aufruf passiert optisch nichts.
undefined und null verhalten sich verschieden: Lässt man timeline weg, wird document.timeline verwendet. Mit null hat die Animation keine Zeitachse und currentTime ändert sich nicht von selbst.
Effekt nicht teilen: Ein KeyframeEffect gehört immer nur zu einer Animation. Weist man ihn einer zweiten Animation zu, verliert die erste ihn. Wer einen Effekt mehrfach braucht, erstellt pro Animation einen neuen, z. B. mit new KeyframeEffect(vorhandenerEffekt).
Kompatibilität: Der Konstruktor und KeyframeEffect werden in Chrome/Edge 84+, Firefox 75+ und Safari 13.1+ unterstützt. ScrollTimeline als Zeitachse gibt es bisher nur in Chromium-Browsern und nicht überall.
Leistung: Wer nur transform und opacity animiert, lässt den Browser meist auf dem Compositor-Thread arbeiten. Das ruckelt weniger als das Animieren von Layout-Eigenschaften wie width oder top.
Barrierefreiheit: Mit matchMedia('(prefers-reduced-motion: reduce)') prüfen, ob Nutzer weniger Bewegung wünschen, und die Animation dann weglassen oder verkürzen.

Siehe auch

Animation KeyframeEffect Element.animate() Animation.prototype.play() Animation.finished Animation.playState