Element : méthode animate()

Syntaxe

animate(keyframes, options)

Paramètres

keyframes

Soit un tableau d'objets image-clé, ou un objet image-clé dont les propriétés sont des tableaux de valeurs à parcourir. Voir les formats d'image-clés pour plus de détails.

options

Soit un entier représentant la durée de l'animation (en millisecondes), ou un objet contenant une ou plusieurs propriétés de synchronisation décrites dans le paramètre options de KeyframeEffect() et/ou les options suivantes :

id Facultatif

Une propriété unique à animate() : Une chaîne de caractères permettant de référencer l'animation.

rangeEnd Facultatif

Définit la fin de la plage d'attachement d'une animation le long de sa chronologie, c'est-à-dire où, le long de la chronologie, une animation se termine. L'équivalent JavaScript de la propriété CSS animation-range-end. rangeEnd peut prendre plusieurs types de valeurs différents, comme suit :

• Une chaîne de caractères qui peut être normal (signifiant qu'aucun changement n'est apporté à la plage d'attachement de l'animation), un type <length-percentage> CSS représentant un décalage, un type <timeline-range-name>, ou type un <timeline-range-name> suivi d'un type <length-percentage>. Par exemple : "normal", "entry" ou "cover 100%".

  Voir animation-range pour une description détaillée des valeurs disponibles. Consultez également le Visualiseur des plages de la chronologie ^(angl.), qui montre exactement ce que signifient les différentes valeurs dans un format visuel facile à comprendre.

• Un objet contenant les propriétés rangeName (une chaîne de caractères) et offset (une propriété CSSNumericValue) représentant respectivement un type <timeline-range-name> et un type <length-percentage>, comme décrit au point précédent. Par exemple : { rangeName: "entry", offset: CSS.percent("100") }.

• Un objet CSSNumericValue représentant un décalage, par exemple : CSS.percent("100").

rangeStart Facultatif

Définit le début de la plage d'attachement d'une animation le long de sa chronologie, c'est-à-dire l'endroit sur la chronologie où l'animation va commencer. Équivalent JavaScript de la propriété CSS animation-range-start. rangeStart peut prendre les mêmes types de valeurs que rangeEnd.

timeline Facultatif

Une propriété propre à animate() : L'objet AnimationTimeline à associer à l'animation. La valeur par défaut de Document.timeline. L'équivalent JavaScript de la propriété CSS animation-timeline.

Valeur de retour

Retourne un objet Animation.

Exemples

Rotation et mise à l'échelle

Dans cet exemple, nous utilisons la méthode animate() pour faire pivoter et mettre à l'échelle un élément.

HTML

<div class="journal">Journal qui tourne<br />donne le vertige</div>

CSS

html,
body {
  height: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: black;
}

.journal {
  padding: 0.5rem;
  text-transform: uppercase;
  text-align: center;
  background-color: white;
  cursor: pointer;
}

JavaScript

const rotationJournal = [
  { transform: "rotate(0) scale(1)" },
  { transform: "rotate(360deg) scale(0)" },
];

const tempsJournal = {
  duration: 2000,
  iterations: 1,
};

const journal = document.querySelector(".journal");

journal.addEventListener("click", () => {
  journal.animate(rotationJournal, tempsJournal);
});

Résultat

Démonstration « Descendre dans le Terrier du lapin »

Dans la démonstration Descendre dans le Terrier du lapin (avec l'API Web Animation), nous utilisons la méthode pratique animate() pour créer et lancer immédiatement une animation sur l'élément #tunnel, afin de le faire défiler vers le haut, à l'infini. Notez le tableau d'objets transmis en tant qu'images clés, ainsi que le bloc d'options de synchronisation.

document.getElementById("tunnel").animate(
  [
    // images-clés
    { transform: "translateY(0px)" },
    { transform: "translateY(-300px)" },
  ],
  {
    // options de synchronisation
    duration: 1000,
    iterations: Infinity,
  },
);

Images clés implicites de départ/arrivée

Le navigateur peut déduire l'état de départ ou d'arrivée d'une animation en utilisant l'état actuel. Par défaut, si une seule image clé est fournie, elle est considérée comme l'état final, et l'état de départ est déduit du style calculé actuel de l'élément. Cependant, vous pouvez définir le décalage (offset) pour indiquer où l'image clé fournie doit être placée dans la chronologie de l'animation.

<div>
  <img
    id="logo"
    src="/shared-assets/images/examples/firefox-logo.svg"
    alt="Logo de Firefox" />
</div>
<button id="execution">Animer - utiliser le début actuel</button>
<button id="execution2">Animer - utiliser la fin actuelle</button>
<button id="execution3">Animer - utiliser les deux fins actuelles</button>

div {
  width: 100%;
}

#logo {
  width: 200px;
  height: 200px;
}

const logo = document.getElementById("logo");
document.getElementById("execution").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)" }, 1000);
});
document.getElementById("execution2").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)", offset: 0 }, 1000);
});
document.getElementById("execution3").addEventListener("click", () => {
  logo.animate({ transform: "translateX(300px)", offset: 0.5 }, 1000);
});

Nous avons défini une seule image dans la chronologie, et il suffit de renseigner les états de début et/ou de fin pour créer une animation complète.

timeline, rangeStart et rangeEnd

Exemple d'utilisation des propriétés timeline, rangeStart et rangeEnd :

const img = document.querySelector("img");

const timeline = new ViewTimeline({
  subject: img,
  axis: "block",
});

img.animate(
  {
    opacity: [0, 1],
    transform: ["scaleX(0)", "scaleX(1)"],
  },
  {
    fill: "both",
    duration: 1,
    timeline,
    rangeStart: "cover 0%",
    rangeEnd: "cover 100%",
  },
);

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'interface Animation
• La méthode Element.getAnimations()
• Les propriétés CSS animation-range-end, animation-range-start, animation-timeline
• Les animations dirigées par le défilement CSS
• L'API Web Animations