---
id: gh-waapi
name: "waapi"
url: https://skills.yangsir.net/skill/gh-waapi
author: heygen-com
domain: ai-frontend-engineering
tags: ["web-animations", "frontend", "animation", "javascript"]
install_count: 36700
rating: 4.60 (120 reviews)
github: https://github.com/heygen-com/hyperframes/tree/main/skills/waapi
---

# waapi

> HyperFrames 的 Web Animations API (WAAPI) 适配器，旨在简化和优化浏览器原生动画在 HyperFrames 中的集成。它支持 `element.animate()` 动画、`Animation currentTime` 寻帧、`document.getAnimations()`、`KeyframeEffect` 定时及填充模式，确保原生浏览器动画在 HyperFrames 环境中确定性地渲染，提供流畅且可控的动画体验。

**Stats**: 36,700 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 原生动画集成与控制

**Before**:

在 HyperFrames 中集成浏览器原生动画时，可能需要手动管理 `requestAnimationFrame` 或依赖 CSS 动画，这常常导致动画与主时间轴不同步，难以精确控制播放进度和状态。对于简单的动画需求，引入如 GSAP 等大型动画库又显得过于笨重。

**After**:

通过 WAAPI 适配器，可以直接利用浏览器原生的 `element.animate()` 功能，将其动画精确同步到 HyperFrames 的时间轴上。实现动画的确定性渲染和精确寻帧，避免了复杂的同步逻辑，同时减少了对外部大型动画库的依赖，提升了开发效率和动画性能。

| Metric | Before | After | Change |
|---|---|---|---|
| 开发效率 | 60分钟 | 10分钟 | -83% |

## Readme

# Web Animations API for HyperFrames

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.

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

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

## Stagger Pattern

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

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

## Validation

After editing a WAAPI composition:

```bash
npx hyperframes lint
npx hyperframes validate
```

## Credits And References

- HyperFrames adapter source: `packages/core/src/runtime/adapters/waapi.ts`.
- MDN Web Animations API guide: 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


---
*Source: https://skills.yangsir.net/skill/gh-waapi*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-waapi/markdown*