Animation.pending — Eigenschaft · JavaScript-Referenz

Signatur

Animation.pending

Beschreibung

Die Eigenschaft Animation.pending der Web Animations API ist true, solange die Animation eine ausstehende Play- oder Pause-Aufgabe hat. Ruft man play() oder pause() auf, wird die Änderung nicht sofort wirksam: Der Browser synchronisiert die Animation zuerst mit dem nächsten Frame bzw. dem Compositor-Thread. In dieser kurzen Übergangsphase meldet pending den Wert true.

Sinnvoll ist die Eigenschaft vor allem beim Debuggen und in Steuerlogik, die wissen muss, ob der von playState gemeldete Zustand schon tatsächlich „angekommen“ ist. So kann playState nach play() bereits "running" melden, während pending noch true ist und startTime noch null sein kann.

Wer auf das Ende des Wartezustands reagieren will, sollte nicht in einer Schleife pending abfragen, sondern auf das Promise Animation.ready warten. Es wird erfüllt, sobald keine Aufgabe mehr aussteht; danach ist pending wieder false.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn eine Play- oder Pause-Aufgabe aussteht, sonst false.

Beispiele

Zustand direkt nach play() und nach ready prüfen

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

// animate() startet die Wiedergabe sofort, der Start steht aber noch aus
console.log(animation.playState, animation.pending);

const run = async () => {
  await animation.ready;
  console.log(animation.playState, animation.pending);
};
run();

running true running false

Ausstehende Pause erkennen

const animation = document.querySelector('.spinner').animate(
  [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }],
  { duration: 800, iterations: Infinity }
);

const pauseAndReport = async () => {
  await animation.ready;      // Start abwarten
  animation.pause();
  console.log('Pause ausstehend:', animation.pending);
  await animation.ready;      // Pause abwarten
  console.log('Pause ausstehend:', animation.pending, animation.playState);
};
pauseAndReport();

Pause ausstehend: true Pause ausstehend: false paused

Doppelte Klicks auf einen Umschalter abfangen

const card = document.querySelector('.card');
const toggle = document.querySelector('#toggle');
const animation = card.animate(
  [{ opacity: 1 }, { opacity: 0.2 }],
  { duration: 600, direction: 'alternate', iterations: Infinity }
);

toggle.addEventListener('click', () => {
  // Solange ein Wechsel aussteht, weitere Klicks ignorieren
  if (animation.pending) {
    console.log('Wechsel läuft noch – Klick ignoriert');
    return;
  }
  animation.playState === 'paused' ? animation.play() : animation.pause();
});

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie animation.pending = false wird im Nicht-Strict-Modus stillschweigend ignoriert und löst im Strict-Modus einen TypeError aus.
Kein Polling: Statt pending wiederholt mit requestAnimationFrame abzufragen, besser await animation.ready verwenden.
playState meldet den angestrebten Zustand bereits während der Wartephase – für den tatsächlich erreichten Zustand zusätzlich pending prüfen.
Während eine Aufgabe aussteht, kann startTime null sein; Berechnungen damit erst nach ready durchführen.
Bei Animationen ohne Zeitleiste (timeline === null) oder in inaktiven/ausgeblendeten Dokumenten kann pending länger true bleiben.
Kompatibilität: in Chrome/Edge 76+, Firefox 59+ und Safari 13.1+ unterstützt; ältere Browser mit dem Polyfill web-animations-js ergänzen.

Siehe auch

Animation.ready Animation.playState Animation.prototype.play() Animation.prototype.pause() Animation.startTime Element.prototype.animate() Animation