Animation.play() — Methode · JavaScript-Referenz

Signatur

Animation.prototype.play()

Beschreibung

Die Methode play() der Schnittstelle Animation startet eine Animation oder setzt sie fort. Ist die Animation pausiert, läuft sie ab der aktuellen Position weiter. Ist sie bereits beendet (playState === "finished"), springt sie an den Anfang zurück (bei negativer playbackRate ans Ende) und läuft erneut ab.

Typische Einsatzfälle sind Animationen, die mit new Animation() oder mit element.animate() erstellt und danach sofort per pause() angehalten wurden. So lassen sie sich später gezielt auslösen, etwa durch einen Klick, beim Scrollen oder wenn ein Element sichtbar wird. Aufrufe von play() auf einer schon laufenden Animation bewirken nichts.

play() startet die Animation asynchron: Zuerst wechselt playState auf "running", während pending noch true ist, bis der Browser den ersten Frame vorbereitet hat. Wenn du genau wissen musst, wann die Animation wirklich läuft, warte auf das Promise animation.ready.

Beispiele

Animation erstellen, pausieren und per Klick starten

const box = document.querySelector('.box');
const button = document.querySelector('#start');

const animation = box.animate(
  [
    { transform: 'translateX(0)' },
    { transform: 'translateX(300px)' }
  ],
  { duration: 1000, easing: 'ease-out', fill: 'forwards' }
);
animation.pause(); // noch nicht abspielen

button.addEventListener('click', () => {
  animation.play();
  console.log(animation.playState);
});

running

Play/Pause-Umschalter

const spinner = document.querySelector('.spinner');
const toggle = document.querySelector('#toggle');

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

toggle.addEventListener('click', () => {
  if (spin.playState === 'running') {
    spin.pause();
    toggle.textContent = 'Weiter';
  } else {
    spin.play(); // setzt an der aktuellen Position fort
    toggle.textContent = 'Pause';
  }
});

Mit new Animation() und auf ready bzw. finished warten

const el = document.querySelector('.banner');

const effect = new KeyframeEffect(
  el,
  [{ opacity: 0 }, { opacity: 1 }],
  { duration: 500, fill: 'forwards' }
);
const fadeIn = new Animation(effect, document.timeline);

const run = async () => {
  fadeIn.play();
  console.log('pending:', fadeIn.pending);
  await fadeIn.ready;
  console.log('läuft wirklich:', fadeIn.playState);
  await fadeIn.finished;
  console.log('fertig:', fadeIn.playState);
};

run();

pending: true läuft wirklich: running fertig: finished

Beendete Animation erneut abspielen

const heart = document.querySelector('.heart');
const pulse = heart.animate(
  [{ transform: 'scale(1)' }, { transform: 'scale(1.3)' }, { transform: 'scale(1)' }],
  { duration: 400 }
);

heart.addEventListener('click', () => {
  // Ist die Animation beendet, startet play() sie von vorn
  pulse.play();
});

// Wichtig · Fallstricke

Beendete Animationen laufen von vorn: Ist playState gleich "finished", setzt play() die currentTime auf 0 zurück (bei negativer playbackRate auf das Ende). Eine Fortsetzung ab der letzten Position findet dann nicht statt.
Unendliche Rückwärtsanimation: Hat die Animation eine negative playbackRate und unendliche Dauer (iterations: Infinity), wirft play() eine InvalidStateError-DOMException, weil es kein Ende gibt, an das sie springen könnte.
Asynchroner Start: Direkt nach play() ist pending noch true. Zeitkritischen Code solltest du nach await animation.ready ausführen.
Keine Timeline: Ohne Timeline (timeline === null) wechselt die Animation zwar in den Zustand "running", bewegt sich aber nicht weiter.
finished-Promise: Nach einem Neustart wird ein neues finished-Promise erzeugt. Hole dir die Referenz also erst nach dem Aufruf von play().
Kompatibilität: Wird von allen modernen Browsern (Chrome, Edge, Firefox, Safari 13.1+) unterstützt. Bei prefers-reduced-motion solltest du auf Animationen verzichten oder sie abschwächen.

Siehe auch

Animation Animation.pause() Animation.reverse() Animation.finish() Animation.cancel() Animation.playState Animation.ready Animation.finished Element.animate() KeyframeEffect