anton-abyzov/vskill

Web Animations API para HyperFrames

O HyperFrames pode buscar animações da Web Animations API através de seu adaptador de tempo de execução waapi. A WAAPI é útil quando você deseja keyframes nativos do navegador com temporização criada em JavaScript e sem dependência de GSAP.

Contrato

• Crie animações de forma síncrona durante a inicialização da composição.
• Use element.animate(...) com duration e iterations finitos.
• Use fill: "both" para que os estados buscados persistam.
• Pause as animações após a criação ou deixe o adaptador pausá-las na primeira busca.
• Evite callbacks e promises para estado crítico de renderização.

O adaptador chama document.getAnimations(), define o currentTime de cada animação para o tempo do HyperFrames em milissegundos e, em seguida, a pausa.

Padrão Básico

<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>

Padrão de Escalonamento (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();
});

Bons Usos

• Movimento DOM leve onde keyframes CSS são muito rígidos e GSAP é desnecessário.
• Animações geradas a partir de dados estruturados.
• Linhas do tempo simples que podem ser representadas como keyframes, atrasos e deslocamentos.

Evite

• iterations infinitas.
• Depender de animation.finished para mutar DOM crítico de renderização.
• Executar relógios separados com requestAnimationFrame, temporizadores ou performance.now().
• Animar propriedades de layout quando transformações e opacidade podem expressar o movimento.
• Assumir que o tempo de início local do clipe é automático. O adaptador WAAPI busca o tempo da animação no nível do documento; modele deslocamentos de clipe com delay ou crie a animação em um elemento cuja visibilidade é controlada pela temporização do HyperFrames.

Validação

Após editar uma composição WAAPI:

npx hyperframes lint
npx hyperframes validate

Créditos e Referências

• Código fonte do adaptador HyperFrames: packages/core/src/runtime/adapters/waapi.ts.
• Guia da Web Animations API da MDN: 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