waapi

用途

waapi 是 HyperFrames 的 Web Animations API（WAAPI）运行时适配器。当你希望使用原生浏览器关键帧、用 JavaScript 创建时间控制，并且不想引入 GSAP 依赖时，可以使用 WAAPI。HyperFrames 可以通过该适配器对 WAAPI 动画进行定位（seek）。

主要能力

适配器的核心行为是：调用 document.getAnimations()，把每个动画的 currentTime 设置为 HyperFrames 的时间（毫秒），然后暂停该动画。这样可以让动画状态与 HyperFrames 的时间线保持一致。

使用方式与编写约定

在合成（composition）初始化期间同步创建动画。使用 element.animate(...)，并设置有限的 duration 和 iterations。使用 fill: "both"，使被定位后的状态能够持续保留。创建动画后暂停它，或者让适配器在首次定位时自动暂停。避免在渲染关键状态中使用回调（callbacks）和 Promise。

基本模式示例（元素带有 data-start、data-duration、data-track-index 属性）：

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

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

适用场景

适合以下情况：轻量级 DOM 动效，CSS 关键帧过于死板，而 GSAP 又显得多余；由结构化数据生成的动画；可以表示为关键帧、延迟和偏移的简单时间线。

限制与避免事项

不要使用无限迭代（infinite iterations）。不要依赖 animation.finished 来修改渲染关键 DOM。不要用 requestAnimationFrame、定时器或 performance.now() 运行独立时钟。当 transform 和 opacity 足以表达运动时，不要动画布局属性。不要假设 clip 局部开始时间是自动处理的：WAAPI 适配器定位的是文档级动画时间，需要用 delay 来建模 clip 偏移，或者把动画创建在由 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

技能介绍

用途

主要能力

使用方式与编写约定

适用场景

限制与避免事项

校验

参考