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

CKTIS / JavaScript

KeyframeEffect — un effet d’animation par images clés

KeyframeEffect décrit la cible, les images clés et les paramètres temporels d’un effet. Un objet Animation distinct contrôle la lecture.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

new KeyframeEffect(target, keyframes, options)
new KeyframeEffect(source)

KeyframeEffect est une interface de Web Animations, et non un élément d’ECMAScript. Elle hérite de AnimationEffect et décrit les changements apportés aux propriétés CSS. Sa construction ne démarre pas la lecture : affectez l’effet à un objet Animation, dont la méthode play() lance la lecture. Le raccourci Element.animate() crée l’effet et l’animation, puis démarre la lecture.

target est un élément ou null. keyframes accepte un tableau d’images clés ou un objet contenant des valeurs de propriétés. options correspond à la durée d’une itération en millisecondes ou à un objet contenant des paramètres tels que duration, delay, iterations, easing et fill. Les valeurs explicites de offset doivent appartenir à [0, 1] et être dans l’ordre non décroissant. new KeyframeEffect(source) copie la définition de l’effet, pas l’état de lecture de l’animation.

getKeyframes() renvoie les images clés avec leurs décalages calculés, et setKeyframes() remplace leur ensemble. La méthode héritée updateTiming() modifie les paramètres temporels, tandis que getComputedTiming() expose la progression calculée. Dans l’exemple, currentTime = 500 sélectionne le milieu d’une seule itération de 1000 ms sans lancer la lecture.

Il s’agit d’une API Window ; Node 24 dans le dépôt ne permet pas d’établir sa disponibilité dans un navigateur. Vérifiez sa disponibilité dans l’environnement cible ; l’exemple vérifie les constructeurs, mais ne démontre pas la prise en charge de toutes les options.

Exemples

(() => {
  if (typeof KeyframeEffect !== "function" || typeof Animation !== "function") {
    throw new Error("Web Animations API required");
  }
  const target = document.createElement("div");
  const effect = new KeyframeEffect(
    target,
    [{ opacity: 0 }, { opacity: 1 }],
    { duration: 1000, easing: "linear" }
  );
  const animation = new Animation(effect, document.timeline);
  animation.currentTime = 500;
  console.log(effect.getKeyframes().length);
  console.log(effect.getComputedTiming().progress);
  animation.cancel();
})();

Résultat

2
0.5

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources