Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

WAAPI : tableau d’images clés et options temporelles

Passez un tableau d’images clés à `Element.animate()` et réglez séparément la durée d’une itération, sa courbe de progression et le nombre d’itérations.

Version : Current web platform; runtime support varies

Syntaxe

element.animate(keyframes, { duration, easing, iterations })
element.animate(keyframes, duration)

element.animate(keyframes, options) crée et lance une animation sur un élément du DOM, puis renvoie l’objet Animation. Cette méthode et ses options temporelles relèvent de l’API Web Animations (WAAPI), et non d’ECMAScript 2024 ou d’une autre édition d’ECMAScript. Leur disponibilité dépend de l’environnement d’exécution.

Dans un tableau d’images clés, chaque objet fixe les valeurs de propriétés CSS animables, comme opacity, à un point de l’itération. offset situe ce point entre 0 et 1, bornes incluses. Les valeurs explicites doivent être dans l’ordre croissant au sens large. Les positions omises sont réparties uniformément : trois images clés sans offset reçoivent 0, 0.5 et 1. Un objet unique avec des tableaux de valeurs par propriété, comme { opacity: [0, 1] }, est un autre format accepté.

Dans les options, une valeur numérique de duration donne la durée d’une seule itération en millisecondes. Passer un nombre en deuxième argument est un raccourci qui ne fixe que duration. iterations indique le nombre total d’itérations : 1 par défaut, 2.5 pour deux itérations complètes et la moitié d’une troisième, et la valeur numérique Infinity pour ne fixer aucune limite finie. Avec une durée positive et finie et un nombre fini d’itérations, la durée active vaut duration * iterations, hors délais.

Dans les options, easing est une fonction de progression CSS écrite sous forme de chaîne, par défaut "linear". Elle règle la progression sur une itération entière sans en modifier la durée. Dans une image clé, easing s’applique de cette image jusqu’à la suivante ; les deux réglages peuvent se combiner.

Exemples

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>WAAPI keyframes and timing</title>
<script>
  (() => {
    const element = document.createElement("div");
    const keyframes = [
      { opacity: 0 },
      { opacity: 1, easing: "ease-in" },
      { opacity: 0 },
    ];
    const animation = element.animate(keyframes, {
      duration: 600,
      easing: "ease-in-out",
      iterations: 2.5,
    });

    const effect = animation.effect;
    const { duration, easing, iterations, activeDuration } = effect.getComputedTiming();
    const offsets = effect.getKeyframes().map(frame => frame.computedOffset);
    console.log(`Offsets: ${offsets.join(", ")}`);
    console.log(`${duration} ms × ${iterations} = ${activeDuration} ms; easing: ${easing}`);
    animation.cancel();
  })();
</script>
</html>

Résultat

Offsets: 0, 0.5, 1
600 ms × 2.5 = 1500 ms; easing: ease-in-out

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur compatible avec WAAPI et consultez la console de développement. L’élément n’est pas ajouté à la page : l’exemple affiche les positions et les paramètres temporels calculés sans attendre, puis annule l’animation.

Leçons associées

  • JavaScript · Leçon 29 · Intermédiaire · Version : 3

Sources