waapi

HyperFrames 向け Web Animations API

HyperFrames は、waapi ランタイムアダプターを通じて Web Animations API のアニメーションをシークできます。WAAPI は、GSAP に依存せず、JavaScript でタイミングを設定したネイティブのブラウザーキーフレームを使いたい場合に便利です。

使用条件

• コンポジションの初期化中に、同期的にアニメーションを作成します。
• 有限の duration と iterations を指定して、element.animate(...) を使います。
• シークした状態が保持されるよう、fill: "both" を指定します。
• アニメーションの作成後に一時停止するか、最初のシーク時にアダプターが一時停止するようにします。
• レンダリングに不可欠な状態には、コールバックやプロミスを使わないでください。

アダプターは 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();
});

適した用途

• CSS キーフレームでは柔軟性に欠け、GSAP は不要な場合の、軽量な DOM モーション。
• 構造化データから生成するアニメーション。
• キーフレーム、遅延、オフセットで表現できるシンプルなタイムライン。

避けること

• 無限の iterations。
• animation.finished に依存して、レンダリングに不可欠な DOM を変更すること。
• requestAnimationFrame、タイマー、performance.now() を使って別のクロックを動かすこと。
• transform と opacity でモーションを表現できる場合に、レイアウトプロパティをアニメーションさせること。
• クリップのローカル開始時刻が自動的に適用されると想定すること。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