Window.requestAnimationFrame()
==============================

La méthode **`window.requestAnimationFrame()`** indique au navigateur qu'on souhaite exécuter une animation et demande que celui-ci exécute une fonction spécifique de mise à jour de l'animation, avant le prochain rafraîchissement à l'écran du navigateur. Cette méthode prend comme argument une fonction de rappel qui sera appelée avant le rafraîchissement du navigateur.

**Note :** Si vous souhaitez animer une nouvelle *frame* durant le prochain affichage, la fonction de rappel doit de nouveau appeler la méthode `requestAnimationFrame()`. Autrement dit, `requestAnimationFrame()` ne fonctionne qu'une fois.

Cette méthode doit être appelée dès que le code est prêt à rafraîchir l'animation. La fonction de rappel contenant l'animation sera ainsi appelée par le navigateur avant le prochain rafraîchissement. La fonction de rappel est généralement appelée 60 fois par seconde. En réalité, cette fréquence correspondra le plus souvent au taux de rafraîchissement de l'écran dans la plupart des navigateurs, d'après les recommandations du W3C. Les appels à `requestAnimationFrame()` sont mis en pause dans la plupart des navigateurs lors d'une exécution dans des onglets en arrière-plan ou dans des `<iframe>` masquées afin d'améliorer les performances et la durée de vie des batteries.

La fonction de rappel reçoit un seul argument, une valeur `DOMHighResTimeStamp`, qui indique le temps actuel (exprimé en nombre de millisecondes écoulées depuis l'origine temporelle). Lorsque plusieurs fonctions de rappel sont mises en attente et que `requestAnimationFrame()` commence à se déclencher pour une image donnée, chaque fonction reçoit le même horodatage, même si du temps s'est écoulé pendant le calcul de la fonction de rappel précédente (dans l'exemple ci-après, on anime uniquement l'image lorsque l'horodatage change, c'est-à-dire à la première fonction de rappel). Cette valeur temporelle est un nombre décimal, exprimant une valeur en millisecondes, avec une précision minimale de 1ms (1000 µs).

**Attention :** Assurez-vous de toujours utiliser le premier argument (ou une autre méthode pour obtenir le temps courant) afin de calculer la progression nécessaire de l'animation pour une *frame*. Sinon, l'animation s'exécutera plus rapidement sur les écrans avec une fréquence de rafraîchissement plus élevée. Voyez l'exemple ci-après pour une technique permettant de faire ce calcul.

Syntaxe
-------


```js
requestAnimationFrame(callback);
```

### Paramètres

`callback`

La fonction à appeler lorsqu'il est temps de mettre à jour l'animation pour le prochain affichage. La fonction de rappel reçoit un seul argument, une valeur `DOMHighResTimeStamp` (semblable à celle renvoyée par `performance.now()`), qui indique le moment où `requestAnimationFrame()` commence à exécuter les fonctions de rappel.

### Valeur de retour

Une valeur entière de type `long` qui est un identifiant unique pour la requête correspondant dans la liste des fonctions de rappel. Il s'agit d'une valeur différente de zéro, mais on ne pourra pas faire d'autres hypothèses sur cette valeur. Celle-ci peut être passée en paramètre de la méthode `window.cancelAnimationFrame()` afin d'annuler l'appel à la fonction de rappel.

Exemple
-------

Dans cet exemple, un élément est animé pour 2 secondes (2000 millisecondes). L'élément se déplace à une vitesse de 0.1px/ms vers la droite. Sa position relative (en pixels CSS) peut donc être calculée en fonction du temps écoulé entre le début de l'animation (en millisecondes) et `0.1 * ecoule`. La position finale de l'élément est située 200px (`0.1 * 2000`) à droite de sa position initiale.


```js
const element = document.getElementById("un-élément-à-animer");
let debut, tempsPrecedent;
let fini = false;

function iteration(chrono) {
  if (debut === undefined) {
    debut = chrono;
  }
  const ecoule = chrono - debut;

  if (tempsPrecedent !== chrono) {
    // Math.min() est utilisée ici afin de s'assurer
    // que l'élément s'arrête exactement à 200px
    const compteur = Math.min(0.1 \* ecoule, 200);
    element.style.transform = `translateX(${compteur}px)`;
    if (compteur === 200) fini = true;
  }

  if (ecoule < 2000) {
    // On arrête l'animation après 2 secondes
    tempsPrecedent = chrono;
    if (!fini) {
      window.requestAnimationFrame(iteration);
    }
  }
}

window.requestAnimationFrame(iteration);
```

Notes
-----

Internet Explorer et Edge, dans les versions antérieures à la version 17, ne déclenchent pas correctement `requestAnimationFrame` avant le prochain cycle d'affichage.

Spécifications
--------------

| Specification |
| --- |
| HTML Standard # dom-animationframeprovider-requestanimationframe |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Voir aussi
----------

* `Window.cancelAnimationFrame()`
* Utiliser `requestAnimationFrame()` pour des animations intelligentes, un billet en anglais de Paul Irish
* Les animations en JavaScript : de `setInterval()` à `requestAnimationFrame()`
* TestUFO : testez les déviations temporelles de votre navigateur sur `requestAnimationFrame()`
* Une précision inférieure à la milliseconde pour l'API `requestAnimationFrame()`, un billet en anglais
* Une prothèse d'émulation (*polyfill*)