anton-abyzov/vskill

HyperFrames 向け Web Animations API

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

契約

• コンポジションの初期化中にアニメーションを同期的に作成します。
• 有限の 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() を使用して別のクロックを実行すること。
• トランスフォームと不透明度で表現できる場合にレイアウトプロパティをアニメーションすること。
• クリップローカルの開始時刻が自動的に設定されることを前提としないこと。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