waapi

FrameVideo 的 Web Animations API

适用场景

以下情况可使用 WAAPI：

• 零依赖动画 — 无需外部库
• 轻量级 DOM 动效 — 简单的变换和透明度变化
• 原生浏览器性能 — 由浏览器优化的关键帧引擎
• 生成式动画 — 根据结构化数据创建动画
• 最小化包体积 — 每 KB 都至关重要时

不要使用

以下情况应避免使用 WAAPI：

• 复杂的时间线编排 — 使用 gsap（时间线控制更出色）
• 默认选择 — 除非你特别需要零依赖，否则使用 gsap
• 纯 CSS 装饰效果 — 使用 css-animations（更简单）
• 3D/WebGL — 使用 three
• 设计工具导出内容 — 使用 lottie

---

快速开始

在 FrameVideo 中使用 WAAPI 创建基本动画：

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

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

  animation.pause();     // Pause immediately
</script>

要点：

1. 使用 fill: "both" 保留跳转到指定时间后的状态
2. 创建动画后调用 animation.pause()
3. 使用有限的 iterations

---

约定

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

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

基本模式

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

适用场景

• 在无需 GSAP 的情况下，为 CSS 关键帧过于僵化的场景添加轻量级 DOM 动效。
• 根据结构化数据生成动画。
• 可用关键帧、延迟和偏移量表示的简单时间线。

避免

• 使用无限的 iterations。
• 依赖 animation.finished 修改渲染关键 DOM。
• 使用 requestAnimationFrame、计时器或 performance.now() 运行独立时钟。
• 当变换和透明度足以表达动效时，避免为布局属性添加动画。
• 假设剪辑的本地起始时间会自动生效。WAAPI 适配器会跳转文档级动画时间；请使用 delay 建模剪辑偏移，或在可见性由 FrameVideo 计时控制的元素上创建动画。

验证

编辑 WAAPI 合成后：

npx framevideo lint      # Check structure
npx framevideo validate  # Check runtime errors
npx framevideo preview   # Scrub timeline to verify seekability

手动检查：

1. 填充模式 — 所有动画均使用 fill: "both"
2. 暂停状态 — 创建动画后暂停
3. 有限迭代次数 — 不存在无限循环
4. 可跳转性 — 拖动预览时间轴时，动画在任意帧都能保持对应状态
5. 性能 — 优先使用变换和透明度，而非布局属性

致谢与参考资料

• FrameVideo 适配器源码：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