Window: requestAnimationFrame() Methode

Syntax

requestAnimationFrame(callback)

Parameter

callback

Die Funktion, die aufgerufen wird, wenn es an der Zeit ist, Ihre Animation für den nächsten Neuzeichnen zu aktualisieren. Diese Callback-Funktion erhält ein einzelnes Argument:

timestamp

Ein DOMHighResTimeStamp, der die Endzeit des Renderns des vorherigen Bildes anzeigt (basierend auf der Anzahl der Millisekunden seit dem time origin). Der Zeitstempel ist eine Dezimalzahl in Millisekunden, jedoch mit einer minimalen Präzision von 1 Millisekunde. Für Window-Objekte (nicht Workers) ist es gleich document.timeline.currentTime. Dieser Zeitstempel wird zwischen allen Fenstern, die auf demselben Agenten laufen (alle gleich-origin-Fenster und vor allem gleich-origin iframes), geteilt — was das Synchronisieren von Animationen über mehrere requestAnimationFrame-Callbacks ermöglicht. Der Zeitstempelwert ist auch vergleichbar mit dem Aufruf von performance.now() zu Beginn der Callback-Funktion, ist jedoch niemals derselbe Wert.

Wenn mehrere Callbacks, die durch requestAnimationFrame() in einer einzigen Bildschleife bereitgestellt werden, beginnen zu feuern, erhält jeder denselben Zeitstempel, obwohl während der Berechnung der Arbeitslast jedes vorherigen Callbacks Zeit vergangen ist.

Rückgabewert

Ein unsigned long integer Wert, die Request-ID, die den Eintrag in der Callback-Erfassungsliste eindeutig identifiziert. Sie sollten keine Annahmen über ihren Wert machen. Sie können diesen Wert an window.cancelAnimationFrame() übergeben, um die Neuzeichen-Callback-Anfrage abzubrechen.

Beispiele

In diesem Beispiel wird ein Element für 2 Sekunden (2000 Millisekunden) animiert. Das Element bewegt sich mit einer Geschwindigkeit von 0,1px/ms nach rechts, so dass seine relative Position (in CSS-Pixeln) in Abhängigkeit von der seit dem Start der Animation verstrichenen Zeit (in Millisekunden) mit 0.1 * elapsed berechnet werden kann. Die Endposition des Elements ist 200px (0.1 * 2000) rechts von seiner Anfangsposition.

const element = document.getElementById("some-element-you-want-to-animate");
let start;

function step(timestamp) {
  if (start === undefined) {
    start = timestamp;
  }
  const elapsed = timestamp - start;

  // Math.min() is used here to make sure the element stops at exactly 200px
  const shift = Math.min(0.1 * elapsed, 200);
  element.style.transform = `translateX(${shift}px)`;
  if (shift < 200) {
    requestAnimationFrame(step);
  }
}

requestAnimationFrame(step);

Die folgenden drei Beispiele veranschaulichen unterschiedliche Ansätze, um den Nullpunkt in der Zeit festzulegen, die Basislinie zur Berechnung des Fortschritts Ihrer Animation in jedem Bild. Wenn Sie sich mit einer externen Uhr synchronisieren möchten, wie z.B. BaseAudioContext.currentTime, ist die höchstpräzise verfügbare Dauer die eines einzelnen Bildes, 16,67 ms @60Hz. Das Zeitstempelargument des Callbacks stellt das Ende des vorherigen Bildes dar, so dass der früheste Zeitpunkt, zu dem Ihr neu berechneter Wert renderbar ist, im nächsten Bild liegt.

In diesem Beispiel wird gewartet, bis der erste Callback ausgeführt wird, um zero zu setzen. Wenn Ihre Animation beim Starten auf einen neuen Wert springt, müssen Sie sie in dieser Weise strukturieren. Wenn Sie nicht mit etwas Externem, wie Audio, synchronisieren müssen, wird dieser Ansatz empfohlen, da einige Browser eine mehrfache Bildverzögerung zwischen dem anfänglichen Aufruf von requestAnimationFrame() und dem ersten Aufruf der Callback-Funktion haben.

let zero;
requestAnimationFrame(firstFrame);
function firstFrame(timestamp) {
  zero = timestamp;
  animate(timestamp);
}
function animate(timestamp) {
  const value = (timestamp - zero) / duration;
  if (value < 1) {
    element.style.opacity = value;
    requestAnimationFrame((t) => animate(t));
  } else element.style.opacity = 1;
}

Dieses Beispiel verwendet document.timeline.currentTime, um den Nullwert vor dem ersten Aufruf von requestAnimationFrame festzulegen. document.timeline.currentTime ist mit dem timestamp-Argument ausgerichtet, sodass der Nullwert dem Zeitstempel des 0ten Bildes entspricht.

const zero = document.timeline.currentTime;
requestAnimationFrame(animate);
function animate(timestamp) {
  const value = (timestamp - zero) / duration; // animation-timing-function: linear
  if (value < 1) {
    element.style.opacity = value;
    requestAnimationFrame((t) => animate(t));
  } else element.style.opacity = 1;
}

Dieses Beispiel animiert unter Verwendung von performance.now(), anstatt des Zeitstempelwertes des Callbacks. Sie könnten dies verwenden, um eine etwas höhere Synchronisierungspräzision zu erreichen, obwohl der zusätzliche Präzisionsgrad variabel und nicht wesentlich erhöht ist.

const zero = performance.now();
requestAnimationFrame(animate);
function animate() {
  const value = (performance.now() - zero) / duration;
  if (value < 1) {
    element.style.opacity = value;
    requestAnimationFrame((t) => animate(t));
  } else element.style.opacity = 1;
}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Window.cancelAnimationFrame()
• DedicatedWorkerGlobalScope.requestAnimationFrame()
• Animate mit JavaScript: von setInterval zu requestAnimationFrame - Blog-Post
• TestUFO: Testen Sie Ihren Webbrowser auf requestAnimationFrame() Timing-Abweichungen
• Firefox wechselt zu uint32_t für die requestAnimationFrame-Anfrage-ID