Animation.updatePlaybackRate() — Methode · JavaScript-Referenz

Signatur

Animation.prototype.updatePlaybackRate(playbackRate)

Beschreibung

updatePlaybackRate() ändert die Geschwindigkeit einer Animation der Web Animations API. Anders als beim direkten Setzen von animation.playbackRate geschieht die Änderung asynchron und synchronisiert: Der Browser gleicht zuerst die aktuelle Zeit der Animation ab, bei Bedarf auch mit einer Animation, die im Compositor-Thread läuft. Erst danach wird die neue Rate übernommen. Dadurch springt die Animation beim Tempowechsel nicht sichtbar.

Bis die Änderung wirksam ist, meldet animation.playbackRate weiterhin den alten Wert. Die neue Rate wird intern als „ausstehende Wiedergaberate“ (pending playback rate) gespeichert. Wer wissen will, wann sie greift, wartet auf animation.ready. Das Promise wird erfüllt, sobald die Rate übernommen wurde.

Typische Einsatzfälle sind Geschwindigkeitsregler für Animationen, Zeitlupe und Zeitraffer in Demos, Rückwärtslaufen mit negativen Werten oder eine Wiedergabegeschwindigkeit, die dem Scrollen oder der Nutzereingabe folgt. Immer wenn eine laufende Animation ihr Tempo ändern soll, ist updatePlaybackRate() dem direkten Setzen von playbackRate vorzuziehen.

Parameter

Name	Typ	Default	Beschreibung
$playbackRate Pflicht	number		Neue Wiedergaberate. `1` ist normale Geschwindigkeit, `2` doppelt so schnell, `0.5` halb so schnell. Negative Werte lassen die Animation rückwärts laufen, `0` hält sie praktisch an.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Wann die neue Rate greift, erfährt man über das Promise animation.ready.

Beispiele

Geschwindigkeitsregler für eine laufende Animation

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

const slider = document.querySelector('#speed'); // <input type="range" min="0.25" max="4" step="0.25">
slider.addEventListener('input', () => {
  // Ruckelfreie Tempoänderung ohne Sprung
  anim.updatePlaybackRate(Number(slider.value));
});

Warten, bis die neue Rate übernommen wurde

const anim = document.body.animate(
  [{ opacity: 1 }, { opacity: 0.2 }],
  { duration: 3000, iterations: Infinity, direction: 'alternate' }
);

anim.updatePlaybackRate(3);
console.log('sofort:', anim.playbackRate); // noch der alte Wert

await anim.ready;
console.log('nach ready:', anim.playbackRate);

sofort: 1 nach ready: 3

Animation per Tastendruck umkehren

const el = document.querySelector('.slider');
const anim = el.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 4000, fill: 'both' }
);

document.addEventListener('keydown', (event) => {
  if (event.key === 'r') {
    // Aktuelle Richtung umdrehen und dabei Tempo und Position beibehalten
    anim.updatePlaybackRate(-anim.playbackRate);
  }
});

// Wichtig · Fallstricke

Verzögerte Wirkung: Direkt nach dem Aufruf liefert playbackRate noch den alten Wert. Wer mit der neuen Rate rechnen will, wartet vorher auf await animation.ready.
Das direkte Setzen von animation.playbackRate = x wirkt sofort. Bei laufenden Animationen im Compositor kann das aber einen sichtbaren Sprung verursachen. updatePlaybackRate() vermeidet das.
Ist die Animation angehalten oder beendet, wird die Rate sofort übernommen, weil nichts synchronisiert werden muss.
Ein Wechsel zwischen positiver und negativer Rate verändert, was „beendet“ bedeutet: Rückwärts endet die Animation bei currentTime = 0, und finished und onfinish verhalten sich entsprechend.
Dieselbe Methode gibt es auch für CSS-Animationen und -Transitions, zum Beispiel über element.getAnimations().
Browser-Unterstützung: Chrome/Edge 76+, Firefox 60+, Safari 13.1+. In älteren Browsern ersatzweise playbackRate direkt setzen und dabei per Feature-Test prüfen: 'updatePlaybackRate' in Animation.prototype.

Siehe auch

Animation.playbackRate Animation.ready Animation.reverse() Animation.play() Element.animate() Animation