waapi

HyperFrames 的 Web Animations API

HyperFrames 可以通过其 waapi 运行时适配器对 Web Animations API 动画进行时间跳转。如果你想使用原生浏览器关键帧，并通过 JavaScript 创建时间设置，同时不依赖 GSAP，WAAPI 会很有用。

契约

• 在合成初始化期间同步创建动画。
• 使用 element.animate(...)，并设置有限的 duration 和 iterations。
• 使用 fill: "both"，以便跳转后的状态持续保留。
• 创建动画后暂停它们，或让适配器在首次跳转时暂停它们。
• 避免使用回调和 Promise 来处理渲染关键状态。

适配器会调用 document.getAnimations()，将每个动画的 currentTime 设置为 HyperFrames 的毫秒级时间，然后暂停动画。

基本模式

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

交错模式

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();
});

适用场景

• 轻量级 DOM 动效：CSS 关键帧过于僵化，且不需要 GSAP。
• 根据结构化数据生成动画。
• 可用关键帧、延迟和偏移量表示的简单时间线。

避免

• 使用无限的 iterations。
• 依赖 animation.finished 来修改渲染关键 DOM。
• 使用 requestAnimationFrame、计时器或 performance.now() 运行独立时钟。
• 动画化布局属性，而变换和透明度就能实现所需效果。
• 假设剪辑的本地起始时间会自动处理。WAAPI 适配器会跳转文档级动画时间；请使用 delay 模拟剪辑偏移，或在可见性由 HyperFrames 计时控制的元素上创建动画。

验证

编辑 WAAPI 合成后：

npx hyperframes lint
npx hyperframes validate

致谢与参考资料

• HyperFrames 适配器源码：packages/core/src/runtime/adapters/waapi.ts。
• MDN Web Animations API 指南：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