Back to Details

waapi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Web Animations API for HyperFrames

适用于HyperFrames的Web Animations API

HyperFrames can seek Web Animations API animations through its 
waapi
runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.
HyperFrames可以通过其
waapi
运行时适配器来定位Web Animations API动画。当你想要使用原生浏览器关键帧，同时用JavaScript定义时序且不依赖GSAP时，WAAPI会非常实用。

Contract

约定

  • Create animations synchronously during composition initialization.
  • Use 
    element.animate(...)
    with finite 
    duration
    and 
    iterations
    .
  • Use 
    fill: "both"
    so seeked states persist.
  • Pause animations after creation or let the adapter pause them on first seek.
  • Avoid callbacks and promises for render-critical state.
The adapter calls 
document.getAnimations()
, sets each animation's 
currentTime
to HyperFrames time in milliseconds, then pauses it.
  • 在合成初始化阶段同步创建动画。
  • 使用
    element.animate(...)
    时设置有限的
    duration
    和
    iterations
    。
  • 使用
    fill: "both"
    以确保定位后的状态得以保留。
  • 创建动画后暂停，或让适配器在首次定位时自动暂停。
  • 避免使用回调和Promise处理渲染关键状态。
适配器会调用
document.getAnimations()
，将每个动画的
currentTime
设置为HyperFrames的时间（以毫秒为单位），然后暂停动画。

Basic Pattern

基础模式

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

Stagger Pattern

stagger模式

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

Good Uses

适用场景

  • Lightweight DOM motion where CSS keyframes are too rigid and GSAP is unnecessary.
  • Generated animations from structured data.
  • Simple timelines that can be represented as keyframes, delays, and offsets.
  • 轻量级DOM动效：CSS关键帧过于僵化，且无需依赖GSAP时。
  • 从结构化数据生成动画。
  • 可通过关键帧、延迟和偏移量表示的简单时间线。

Avoid

注意避免

  • Infinite 
    iterations
    .
  • Depending on 
    animation.finished
    to mutate render-critical DOM.
  • Running separate clocks with 
    requestAnimationFrame
    , timers, or 
    performance.now()
    .
  • Animating layout properties when transforms and opacity can express the motion.
  • Assuming clip-local start time is automatic. WAAPI adapter seeks document-level animation time; model clip offsets with 
    delay
    or create the animation on an element whose visibility is controlled by HyperFrames timing.
  • 设置无限
    iterations
    。
  • 依赖
    animation.finished
    修改渲染关键DOM。
  • 使用
    requestAnimationFrame
    、计时器或
    performance.now()
    运行独立时钟。
  • 当可以用transform和opacity实现动效时，仍对布局属性执行动画。
  • 假设片段本地起始时间是自动设置的。WAAPI适配器会定位文档级动画时间；需用
    delay
    模拟片段偏移，或在受HyperFrames时序控制可见性的元素上创建动画。

Validation

验证

After editing a WAAPI composition:
bash
npx hyperframes lint
npx hyperframes validate
编辑WAAPI合成内容后：
bash
npx hyperframes lint
npx hyperframes validate

Credits And References

致谢与参考