Animation.playState — Eigenschaft · JavaScript-Referenz

Signatur

Animation.playState

Beschreibung

Die schreibgeschützte Eigenschaft Animation.playState der Web Animations API gibt an, in welchem Wiedergabezustand sich eine Animation gerade befindet. Sie eignet sich, um Bedienelemente wie Play/Pause-Schalter zu steuern, den Zustand vor einem Methodenaufruf zu prüfen oder den Status zu Debug-Zwecken auszugeben.

Mögliche Werte:

"idle" – Die aktuelle Zeit ist nicht aufgelöst und es steht keine Aufgabe an, z. B. nach cancel().
"running" – Die Animation läuft (auch während ein play() noch aussteht).
"paused" – Die Animation wurde angehalten, z. B. per pause().
"finished" – Die Animation hat eine ihrer Grenzen erreicht (Ende bzw. Anfang bei negativer Wiedergaberate).

Der Wert wird ausschließlich über Methoden wie play(), pause(), finish(), cancel() und reverse() verändert – direktes Zuweisen hat keine Wirkung. Ob ein Zustandswechsel noch aussteht, verrät die separate Eigenschaft Animation.pending.

Rückgabewert

Typ

"idle" | "running" | "paused" | "finished"

Beschreibung

Eine Zeichenkette, die den aktuellen Wiedergabestatus der Animation beschreibt.

Beispiele

Status im Lebenszyklus einer Animation abfragen

const box = document.querySelector('.box');
const anim = box.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 1000, fill: 'forwards' }
);

console.log(anim.playState); // direkt nach animate()
anim.pause();
console.log(anim.playState);
anim.finish();
console.log(anim.playState);
anim.cancel();
console.log(anim.playState);

running paused finished idle

Play/Pause-Schalter anhand von playState

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

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

button.addEventListener('click', () => {
  if (anim.playState === 'running') {
    anim.pause();
    button.textContent = 'Fortsetzen';
  } else {
    anim.play();
    button.textContent = 'Pausieren';
  }
});

Alle laufenden Animationen der Seite pausieren

const pauseAllRunning = () => {
  const running = document
    .getAnimations()
    .filter((a) => a.playState === 'running');
  running.forEach((a) => a.pause());
  return running.length;
};

console.log(`${pauseAllRunning()} Animation(en) pausiert`);

3 Animation(en) pausiert

Auf das Ende warten statt playState zu pollen

const fadeOut = async (el) => {
  const anim = el.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 400 });
  await anim.finished;
  console.log(anim.playState);
  el.remove();
};

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

finished

// Wichtig · Fallstricke

Schreibgeschützt: anim.playState = 'paused' bewirkt nichts (im Strict-Mode wirft es einen TypeError). Nutze stattdessen pause(), play() usw.
Kein "pending" mehr: Ältere Spezifikationsstände und alte Browser-Versionen kannten den Wert "pending". Heute steht dafür die boolesche Eigenschaft Animation.pending zur Verfügung.
Nicht pollen: Statt playState in einer Schleife oder per requestAnimationFrame abzufragen, besser das Promise animation.finished oder die Events finish/cancel verwenden.
Bei Endlos-Animationen (iterations: Infinity) wird "finished" nur über einen expliziten finish()-Aufruf erreicht – der wirft bei positiver Wiedergaberate allerdings einen InvalidStateError.
Auch CSS-Animationen und -Transitions (CSSAnimation, CSSTransition) über element.getAnimations() liefern playState. Nicht verwechseln mit der CSS-Eigenschaft animation-play-state, die nur running/paused kennt.
Browser-Unterstützung: in Chrome, Edge, Firefox und Safari (ab 13.1) vorhanden; für sehr alte Browser gibt es das Polyfill web-animations-js.

Siehe auch

Animation Animation.pending Animation.finished Animation.prototype.play() Animation.prototype.pause() Animation.prototype.cancel() Element.prototype.animate() Document.prototype.getAnimations()