[ Web Proxy ]
URL:
Viewing: https://developer.mozilla.org/fr/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API [Back]  [Original]
Utilisation de l'API Web Animations - Les API Web | MDN
HTML

HTML: Markup language

HTML reference
HTML guides
Markup languages
CSS

CSS: Styling language

CSS reference
CSS guides
Layout cookbook
JavaScriptJS

JavaScript: Scripting language

JS reference
JS guides
Web APIs

Web APIs: Programming interfaces

Web API reference
Web API guides
All

All web technology

Technologies
Topics
Learn

Learn web development

Frontend developer course
Learn HTML
Learn CSS
Learn JavaScript
Tools

Discover our tools

About

Get to know MDN better

Blog
Basculer la barre latrale
  1. Web
  2. Les API Web
  3. Web Animations API
  4. Utilisation de l'API Web Animations
Thme
  • Automatique
  • Clair
  • Sombre
Franais
Se souvenir de la langue En savoir plus

Cette page a t traduite partir de l'anglais par la communaut. Vous pouvez contribuer en rejoignant la communaut francophone sur MDN Web Docs.

View in English Always switch to English

Utilisation de l'API Web Animations

L'API Web Animations nous permet de construire des animations et de contrler leur lecture avec JavaScript. Cet article vous met sur la bonne voie avec des dmonstrations et des tutoriels inspirs d' Alice au pays des merveilles .

Dans cet article

Dcouvrir l'API Web Animations

L'API Web Animations ouvre le moteur d'animation du navigateur aux dveloppeureuses et la manipulation par JavaScript. Cette API a t conue pour sous-tendre les implmentations d'Animations CSS et de Transitions CSS, et laisse la porte ouverte de futurs effets d'animation. C'est l'une des faons les plus performantes d'animer sur le Web, laissant le navigateur effectuer ses propres optimisations internes sans dtournements, coercition, ni Window.requestAnimationFrame().

Avec l'API Web Animations, nous pouvons dplacer des animations interactives des feuilles de style vers JavaScript, sparant ainsi la prsentation du comportement. Nous n'avons plus besoin de recourir des techniques lourdes pour le DOM comme l'criture de proprits CSS et l'application de classes aux lments pour contrler le sens de lecture. Et contrairement au CSS purement dclaratif, JavaScript nous permet aussi de dfinir dynamiquement des valeurs, des proprits jusqu'aux dures. Pour crer des bibliothques d'animation personnalises et des animations interactives, l'API Web Animations peut tre l'outil idoine. Voyons ce qu'elle permet.

Cette page contient une suite d'exemples utilisant l'API Web Animations, inspirs de Alice au pays des merveilles. Ces exemples ont t crs et partags gracieusement par Rachel Nabors (angl.). L'ensemble complet d'exemples (angl.) est disponible sur CodePen ; ici, nous prsentons ceux qui sont pertinents pour notre documentation.

crire des animations CSS avec l'API Web Animations

Une faon familire d'aborder l'API Web Animations consiste partir d'un sujet que la plupart des dveloppeureuses Web ont dj expriment : les animations CSS. Les animations CSS ont une syntaxe familire qui se prte bien la dmonstration.

La version CSS

Voici une animation de  tumbling  (ou acrobatie en franais) crite en CSS montrant Alice tombant dans le terrier qui mne au pays des merveilles :

Remarquez que l'arrire-plan se dplace, Alice tourne et sa couleur change avec un dcalage par rapport sa rotation. Nous allons nous concentrer uniquement sur Alice pour ce tutoriel. Vous pouvez consulter le code source complet en cliquant sur  Play  dans le bloc de code. Voici le CSS simplifi qui contrle l'animation d'Alice :

css
#alice {
  animation: alice-tumbling infinite 3s linear;
}

@keyframes alice-tumbling {
  0% {
    color: black;
    transform: rotate(0) translate3d(-50%, -50%, 0);
  }
  30% {
    color: #431236;
  }
  100% {
    color: black;
    transform: rotate(360deg) translate3d(-50%, -50%, 0);
  }
}

Cela change la couleur d'Alice et la rotation de sa transformation sur 3 secondes un rythme constant (linear) et boucle indfiniment. Dans le bloc @keyframes, on voit qu' 30% de chaque boucle (environ 0,9s), la couleur d'Alice passe du noir un bordeaux profond, puis revient au noir la fin de la boucle.

Transposer en JavaScript

Essayons maintenant de crer la mme animation avec l'API Web Animations.

Reprsenter les images-cls

La premire chose faire est de crer un objet Keyframe correspondant notre bloc @keyframes en CSS :

js
const aliceTumbling = [
  { transform: "rotate(0) translate3d(-50%, -50%, 0)", color: "black" },
  { color: "#431236", offset: 0.3 },
  { transform: "rotate(360deg) translate3d(-50%, -50%, 0)", color: "black" },
];

Ici, nous utilisons un tableau contenant plusieurs objets. Chaque objet reprsente une cl de l'animation CSS d'origine. Cependant, contrairement au CSS, l'API Web Animations n'a pas besoin qu'on lui indique explicitement les pourcentages le long de l'animation auxquels chaque cl doit apparatre. Elle divise automatiquement l'animation en parts gales en fonction du nombre de cls fourni. Cela signifie qu'un objet d'images-cls trois entres joue la cl du milieu 50% de chaque boucle, sauf indication contraire.

Quand on veut fixer explicitement le dcalage d'une cl par rapport aux autres, on peut dfinir un dcalage directement dans l'objet, spar de la dclaration par une virgule. Dans l'exemple ci-dessus, pour s'assurer que la couleur d'Alice change 30% (et non 50%), on lui donne offset: 0.3.

Actuellement, il faut fournir au moins deux images-cls (reprsentant les tats de dbut et de fin de la squence). Si la liste ne contient qu'une seule entre, Element.animate() peut lever une exception DOMException de type NotSupportedError dans certains navigateurs, en attendant leur mise jour.

En rsum : les cls sont espaces uniformment par dfaut, sauf si vous dfinissez un dcalage sur une cl. Pratique.

Reprsenter les proprits de minutage

Nous devons aussi crer un objet de proprits de minutage correspondant aux valeurs de l'animation d'Alice :

js
const aliceTiming = {
  duration: 3000,
  iterations: Infinity,
};

On remarque quelques diffrences avec la reprsentation CSS :

  • La dure est en millisecondes plutt qu'en secondes 3000 et non 3s. Comme setTimeout() et Window.requestAnimationFrame(), l'API Web Animations ne prend que des millisecondes.
  • On utilise iterations et non iteration-count.

Note : Il existe de petites diffrences de terminologie entre les animations CSS et les animations Web. Par exemple, les Web Animations n'utilisent pas la chane de caractres 'infinite', mais le mot-cl JavaScript Infinity. Et au lieu de timing-function, on utilise easing. Nous ne listons pas de valeur easing ici car, contrairement aux animations CSS o la valeur par dfaut de animation-timing-function est ease, l'API Web Animations utilise par dfaut linear ce qui convient ici.

Assembler les pices

Il est temps d'assembler le tout avec la mthode Element.animate() :

js
document.getElementById("alice").animate(aliceTumbling, aliceTiming);

Et voil : l'animation dmarre :

La mthode animate() peut tre appele sur n'importe quel lment du DOM qui peut tre anim avec CSS. Elle peut s'crire de plusieurs faons. Au lieu de crer des objets spars pour les images-cls et le minutage, on peut passer leurs valeurs directement, ainsi :

js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3d(-50%, -50%, 0)", color: "black" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3d(-50%, -50%, 0)", color: "black" },
  ],
  {
    duration: 3000,
    iterations: Infinity,
  },
);

Mieux encore, si l'on ne veut prciser que la dure de l'animation, sans ses itrations (par dfaut, une animation s'excute une fois), on peut passer uniquement la dure en millisecondes :

js
document.getElementById("alice").animate(
  [
    { transform: "rotate(0) translate3d(-50%, -50%, 0)", color: "black" },
    { color: "#431236", offset: 0.3 },
    { transform: "rotate(360deg) translate3d(-50%, -50%, 0)", color: "black" },
  ],
  3000,
);

Contrler la lecture avec play(), pause(), reverse() et updatePlaybackRate()

On peut crire des animations CSS avec l'API Web Animations, mais l o l'API est vraiment utile, c'est pour manipuler la lecture. L'API offre plusieurs mthodes pour contrler la lecture. Observons la mise en pause et la lecture dans l'exemple  Suis le lapin blanc  :

Dans cet exemple, le lapin blanc a une animation qui le fait descendre dans un terrier. Elle n'est dclenche que lorsque l'utilisateurice clique dessus.

Mettre en pause et lire des animations

Nous pouvons animer le lapin avec animate() comme d'habitude :

js

La mthode Element.animate() dmarre immdiatement aprs son appel. Pour viter que le gteau ne se  mange  tout seul avant que la personne n'ait le temps de cliquer, on appelle Animation.pause() juste aprs sa dfinition :

js

Note : Alternativement, on peut dfinir animationDescenteLapin avec le constructeur Animation(), qui ne commence pas jouer avant l'appel play().

Nous pouvons ensuite utiliser Animation.play() pour lancer l'animation quand on le souhaite. Plus prcisment, nous voulons la lier une action de clic. On y parvient ainsi :

js

Quand une personne clique ou touche le lapin, nous pouvons appeler ilDescend pour faire jouer toutes les animations.

Autres mthodes utiles

Outre la mise en pause et la lecture, on peut utiliser les mthodes suivantes sur une animation :

Regardons d'abord playbackRate : une valeur ngative fait jouer une animation l'envers. Dans De l'autre ct du miroir, Alice se rend dans un monde o elle doit courir pour rester sur place et courir deux fois plus vite pour avancer. Dans l'exemple de la course de la Reine Rouge, Alice et la Reine Rouge courent pour rester sur place :

Comme les jeunes enfants se fatiguent vite, contrairement aux pices d'checs automates, Alice ralentit constamment. On peut le faire en appliquant une dcroissance son playbackRate. On utilise updatePlaybackRate() plutt que d'affecter directement playbackRate afin d'obtenir une mise jour fluide :

js
setInterval(() => {
  // S'assurer que le taux de lecture ne descend jamais sous 0.4
  if (redQueenAlice.playbackRate > 0.4) {
    redQueenAlice.updatePlaybackRate(redQueenAlice.playbackRate * 0.9);
  }
  adjustBackgroundPlayback();
}, 1000);

Mais si on les encourage par un clic ou un tap, ilselles acclrent en multipliant leur playbackRate :

js
function goFaster() {
  // Un clic ou un tap sur l'cran les fait acclrer
  redQueenAlice.updatePlaybackRate(redQueenAlice.playbackRate * 1.1);
  adjustBackgroundPlayback();
}

document.addEventListener("click", goFaster);
document.addEventListener("touchstart", goFaster);

Les lments d'arrire-plan ont aussi des playbackRate impacts lors d'un clic ou d'un tap. Leurs taux de lecture drivent de celui d'Alice, comme ci-dessous. Que se passe-t-il si vous faites courir Alice et la Reine Rouge deux fois plus vite ? Et si vous les laissez ralentir ?

js
/* Alice se fatigue si vite !
  Toutes les quelques secondes, on rduit son taux de lecture pour la ralentir un peu.
*/
const sceneries = [
  foreground1Movement,
  foreground2Movement,
  background1Movement,
  background2Movement,
];

function adjustBackgroundPlayback() {
  // Si Alice et la Reine Rouge courent  une vitesse comprise entre 0.8 et 1.2,
  // l'arrire-plan ne bouge pas.
  // Mais si elles passent sous 0.8, l'arrire-plan glisse en arrire
  if (redQueenAlice.playbackRate < 0.8) {
    sceneries.forEach((anim) => {
      anim.updatePlaybackRate(-redQueenAlice.playbackRate / 2);
    });
  } else if (redQueenAlice.playbackRate > 1.2) {
    sceneries.forEach((anim) => {
      anim.updatePlaybackRate(redQueenAlice.playbackRate / 2);
    });
  } else {
    sceneries.forEach((anim) => {
      anim.updatePlaybackRate(0);
    });
  }
}
adjustBackgroundPlayback();

Rendre persistants les styles d'animation

Lorsqu'on anime des lments, un cas d'usage courant consiste conserver l'tat final de l'animation aprs sa fin. Une mthode parfois employe consiste rgler le mode de remplissage sur forwards. Cependant, il n'est pas recommand d'utiliser les modes de remplissage pour faire persister indfiniment l'effet d'une animation, pour deux raisons :

  • Le navigateur doit conserver l'tat de l'animation tant qu'elle reste active, donc l'animation continue de consommer des ressources bien qu'elle ne s'anime plus. Notez que cela est en partie attnu par la suppression automatique des animations avec remplissage par le navigateur.
  • Les styles appliqus par les animations ont une priorit plus leve dans la cascade que les styles spcifis, ce qui peut les rendre difficiles surcharger au besoin.

Une meilleure approche consiste utiliser Animation.commitStyles(). Cette mthode crit les valeurs calcules des styles courants de l'animation dans l'attribut style de son lment cible, aprs quoi l'lment peut tre remis en forme normalement.

Suppression automatique des animations avec remplissage

Il est possible de dclencher un grand nombre d'animations sur un mme lment. Si elles sont indfinies (c'est--dire remplies vers l'avant), cela peut entraner une liste d'animations norme, pouvant crer une fuite mmoire. Pour cette raison, les navigateurs suppriment automatiquement les animations avec remplissage aprs qu'elles ont t remplaces par de nouvelles animations, sauf si lale dveloppeureuse indique explicitement de les conserver.

Les animations sont supprimes lorsque toutes les conditions suivantes sont runies :

  • L'animation est avec remplissage (sa proprit fill est forwards si elle joue en avant, backwards si elle joue en arrire, ou both).
  • L'animation est termine. (Remarquez qu' cause de fill, elle est toujours en vigueur.)
  • La chronologie de l'animation est monotone croissante. (C'est toujours vrai pour DocumentTimeline ; d'autres chronologies comme scroll-timeline peuvent reculer.)
  • L'animation n'est pas contrle par un balisage dclaratif comme le CSS.
  • Chaque effet de style de AnimationEffect de l'animation est surcharg par une autre animation qui satisfait aussi toutes les conditions ci-dessus. (Typiquement, lorsque deux animations dfinissent la mme proprit de style du mme lment, la plus rcente remplace l'autre.)

Les quatre premires conditions garantissent que, sans intervention de JavaScript, l'effet de l'animation ne change jamais et ne se termine jamais. La dernire condition garantit que l'animation n'affecte plus le style d'aucun lment : elle a t totalement remplace.

Quand l'animation est supprime automatiquement, l'vnement remove est dclench.

Pour empcher le navigateur de supprimer automatiquement des animations, appelez la mthode persist() de l'animation.

La proprit replaceState de l'animation vaut removed si l'animation a t supprime, persisted si vous avez appel persist() sur l'animation, ou active sinon.

Extraire des informations des animations

Imaginez d'autres usages de playbackRate, comme amliorer l'accessibilit pour les personnes souffrant de troubles vestibulaires en leur permettant de ralentir les animations sur tout un site. Impossible en CSS sans recalculer les dures dans chaque rgle, mais avec l'API Web Animations, on peut utiliser Document.getAnimations pour parcourir chaque animation de la page et diviser par deux leur playbackRate, comme suit :

js
document.getAnimations().forEach((animation) => {
  animation.updatePlaybackRate(animation.playbackRate * 0.5);
});

Avec l'API Web Animations, il suffit de changer une seule proprit.

Autre chose difficile raliser avec les seules animations CSS : crer des dpendances bases sur des valeurs fournies par d'autres animations. Par exemple, dans l'exemple de jeu  Alice grandit et rtrcit , vous avez peut-tre remarqu quelque chose d'trange concernant la dure du gteau :

js
document.getElementById("eat-me-sprite").animate([], {
  duration: aliceChange.effect.getComputedTiming().duration / 2,
});

Pour comprendre ce qui se passe ici, regardons l'animation d'Alice :

js
const aliceChange = document
  .getElementById("alice")
  .animate(
    [
      { transform: "translate(-50%, -50%) scale(.5)" },
      { transform: "translate(-50%, -50%) scale(2)" },
    ],
    {
      duration: 8000,
      easing: "ease-in-out",
      fill: "both",
    },
  );

L'animation d'Alice la fait passer de la moiti de sa taille deux fois sa taille sur 8 secondes. Puis nous la mettons en pause :

js
aliceChange.pause();

Si nous l'avions laisse en pause au dbut, elle commence la moiti de sa taille finale, comme si elle a dj bu toute la bouteille. Nous voulons placer la  tte de lecture  de son animation au milieu, pour qu'elle soit dj mi-chemin. Nous pourrions le faire en rglant Animation.currentTime sur 4 secondes, ainsi :

js
aliceChange.currentTime = 4000;

Mais pendant le travail sur cette animation, nous pourrions changer souvent la dure. Mieux vaut donc rgler currentTime de manire dynamique, pour ne pas avoir modifier deux endroits la fois. C'est possible en se rfrant la proprit Animation.effect d'aliceChange, qui retourne un objet contenant tous les dtails de l'effet ou des effets actifs sur Alice :

js
aliceChange.currentTime = aliceChange.effect.getComputedTiming().duration / 2;

effect nous permet d'accder aux images-cls et aux proprits de minutage de l'animation aliceChange.effect.getComputedTiming() pointe vers l'objet de minutage d'Alice il contient sa duration. On peut la diviser par deux pour obtenir le milieu de la chronologie et rgler Alice une hauteur normale. On peut alors inverser et lire son animation dans un sens comme dans l'autre pour la faire grandir ou rapetisser.

On peut faire de mme pour fixer les dures du gteau et de la bouteille :

js
const drinking = document
  .getElementById("liquid")
  .animate([{ height: "100%" }, { height: "0" }], {
    fill: "forwards",
    duration: aliceChange.effect.getComputedTiming().duration / 2,
  });
drinking.pause();

Les trois animations dpendent maintenant d'une seule dure, que nous pouvons modifier facilement en un seul endroit.

On peut aussi utiliser l'API Web Animations pour dterminer le temps courant d'une animation. La partie se termine lorsque vous n'avez plus de gteau manger ou que la bouteille est vide. La vignette prsente dpend de l'avancement d'Alice dans son animation : a-t-elle trop grandi et ne peut-elle plus entrer par la petite porte, ou est-elle trop petite et ne peut-elle pas atteindre la cl pour ouvrir la porte ? Nous pouvons dterminer si elle est du ct  grand  ou  petit  en prenant currentTime et en le divisant par activeDuration :

js
const endGame = () => {
  // obtenir la position de la tte de lecture sur la chronologie d'Alice
  const alicePlayhead = aliceChange.currentTime;
  const aliceTimeline = aliceChange.effect.getComputedTiming().activeDuration;

  // arrter l'animation d'Alice et les autres
  stopPlayingAlice();

  // selon le tiers dans lequel on se trouve
  const aliceHeight = alicePlayhead / aliceTimeline;

  if (aliceHeight <= 0.333) {
    // Alice a rapetiss !
    // 
  } else if (aliceHeight >= 0.666) {
    // Alice a grandi !
    // 
  } else {
    // Alice n'a pas chang de faon notable
    // 
  }
};

Rappels et promesses

Les animations et transitions CSS ont leurs propres couteurs d'vnements, et c'est aussi possible avec l'API Web Animations :

  • onfinish est le gestionnaire de l'vnement finish et peut tre dclench manuellement avec finish().
  • oncancel est le gestionnaire de l'vnement cancel et peut tre dclench avec cancel().

Ici, nous configurons les rappels pour le gteau, la bouteille et Alice afin qu'ilselles dclenchent la fonction endGame :

js
// Lorsque le gteau ou la bouteille est termin
nommingCake.onfinish = endGame;
drinking.onfinish = endGame;

// Alice atteint la fin de son animation
aliceChange.onfinish = endGame;

Mieux encore, l'API Web Animations fournit aussi une promesse finished qui se rsout quand l'animation se termine, ou est rejete si elle est annule.

Conclusion

Voil les fonctionnalits de base de l'API Web Animations. Vous devez dsormais tre prte  sauter dans le terrier du lapin  de l'animation dans le navigateur et crire vos propres expriences d'animation.

Voir aussi

Aider amliorer MDN

Cette page vous a-t-elle t utile ?
Oui Non
Apprendre contribuer

Cette page a t modifie le 2 sept. 2026 par les contributeurices du MDN.

Voir cette page sur GitHub Signaler un problme avec ce contenu
Effacer le filtre
  1. Web Animations API
  2. Guides
    1. Utilisation de l'API Web Animations
    2. Web Animations API Concepts
    3. Keyframe Formats
    4. Trucs et astuces pour les animations CSS
  3. Interfaces
    1. Animation
    2. AnimationEffect
    3. AnimationEvent
    4. AnimationTimeline
    5. AnimationPlaybackEvent
    6. DocumentTimeline
    7. KeyframeEffect
    8. ScrollTimeline
    9. ViewTimeline
  4. Proprits
    1. Document.timeline
  5. Mthodes
    1. Document.getAnimations()
    2. Element.animate()
    3. Element.getAnimations()
MDN

Votre modle pour un internet meilleur.

MDN
Contribuer
Dveloppeureuses
Mozilla

Certaines parties de ce contenu sont protges par le droit d'auteur 19982026 des contributeurs individuels de mozilla.org. Contenu disponible sous une licence Creative Commons.

Web Proxy Viewer  |  New URL  |  Original Page