anton-abyzov/vskill

API Web Animations pour HyperFrames

HyperFrames peut parcourir les animations de l'API Web Animations grâce à son adaptateur d'exécution waapi. WAAPI est utile lorsque vous souhaitez utiliser des keyframes natives du navigateur avec un timing créé en JavaScript et sans dépendance à GSAP.

Contrat

• Créez les animations de manière synchrone lors de l'initialisation de la composition.
• Utilisez element.animate(...) avec une duration et des iterations finies.
• Utilisez fill: "both" pour que les états parcourus persistent.
• Mettez les animations en pause après leur création ou laissez l'adaptateur les mettre en pause lors du premier parcours.
• Évitez les rappels et les promesses pour les états critiques du rendu.

L'adaptateur appelle document.getAnimations(), définit le currentTime de chaque animation au temps HyperFrames en millisecondes, puis la met en pause.

Modèle de base

<div id="orb" class="clip orb" data-start="2" data-duration="3" data-track-index="2"></div>

<script>
  const orb = document.getElementById("orb");
  const animation = orb.animate(
    [
      { transform: "translate3d(-160px, 0, 0) scale(0.8)", opacity: 0 },
      { transform: "translate3d(0, 0, 0) scale(1)", opacity: 1, offset: 0.35 },
      { transform: "translate3d(120px, 0, 0) scale(1.08)", opacity: 1 },
    ],
    {
      duration: 3000,
      delay: 2000,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",
      iterations: 1,
    },
  );

  animation.pause();
</script>

Modèle de décalage (stagger)

document.querySelectorAll(".token").forEach((token, index) => {
  const animation = token.animate(
    [
      { transform: "translateY(24px)", opacity: 0 },
      { transform: "translateY(0)", opacity: 1 },
    ],
    {
      duration: 620,
      delay: index * 80,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",
      iterations: 1,
    },
  );
  animation.pause();
});

Bonnes utilisations

• Mouvement DOM léger lorsque les keyframes CSS sont trop rigides et GSAP inutile.
• Animations générées à partir de données structurées.
• Timelines simples pouvant être représentées par des keyframes, des délais et des décalages.

À éviter

• Itérations (iterations) infinies.
• Dépendre de animation.finished pour muter le DOM critique pour le rendu.
• Exécuter des horloges séparées avec requestAnimationFrame, des minuteries, ou performance.now().
• Animer des propriétés de mise en page lorsque les transformations et l'opacité peuvent exprimer le mouvement.
• Supposer que le temps de début local du clip est automatique. L'adaptateur WAAPI parcourt le temps d'animation au niveau du document ; modélisez les décalages du clip avec delay ou créez l'animation sur un élément dont la visibilité est contrôlée par le timing HyperFrames.

Validation

Après avoir modifié une composition WAAPI :

npx hyperframes lint
npx hyperframes validate

Crédits et références

• Source de l'adaptateur HyperFrames : packages/core/src/runtime/adapters/waapi.ts.
• Guide MDN sur l'API Web Animations : https://developer.mozilla.org/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API
• MDN Animation.currentTime : https://developer.mozilla.org/en-US/docs/Web/API/Animation/currentTime