用於 HyperFrames 的 Web Animations API
HyperFrames 可透過其 waapi 運行時適配器來搜尋 Web Animations API 動畫。當您需要原生瀏覽器關鍵幀，搭配 JavaScript 建立的時間控制，且無需 GSAP 依賴時，WAAPI 非常實用。
契約
- 在組合初始化期間同步建立動畫。
- 使用具有有限
duration和iterations的element.animate(...)。 - 使用
fill: "both"以便搜尋後的狀態能持久保留。 - 在建立動畫後將其暫停，或讓適配器在第一次搜尋時暫停它們。
- 避免在渲染關鍵狀態中使用回呼和 Promise。
適配器會呼叫 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