GSAP 整合模式
若要將 GSAP 與 Helios 一起使用,你必須使用 Helios 的影格狀態來驅動 GSAP 時間線實例。這使得 GSAP 動畫可以被拉動、暫停以及逐影格渲染。
快速開始
「暫停時間線」模式
- 建立一個
paused: true的 GSAP 時間線。 - 訂閱 Helios 的更新。
- 在訂閱函式中,將 Helios 的影格計數轉換為秒數。
- 呼叫
timeline.seek(seconds)以同步。
<script type="module">
import { Helios } from '@helios-project/core';
import { gsap } from 'gsap';
// 1. 初始化 Helios
const helios = new Helios({
fps: 30,
durationInSeconds: 5,
});
// 2. 設定 GSAP 時間線(關鍵:必須 PAUSED)
const tl = gsap.timeline({ paused: true });
// 3. 定義動畫
tl.to(".box", {
rotation: 360,
x: 100,
duration: 2,
ease: "power1.inOut"
})
.to(".box", {
scale: 2,
duration: 2
});
// 4. 訂閱並同步
helios.subscribe((state) => {
// 將影格計數轉換為秒數
const timeInSeconds = state.currentFrame / helios.fps;
// 讓 GSAP 移動到精確的時間點
tl.seek(timeInSeconds);
});
// 5. 綁定預覽
helios.bindToDocumentTimeline();
window.helios = helios;
</script>
關鍵規則
- 務必暫停: GSAP 時間線必須以
{ paused: true }初始化。如果讓它自動播放,它會與 Helios 爭奪控制權。 - 使用 Seek: 除非你計算出標準化的 0-1 數值,否則不要使用
tl.progress()。由於 Helios 知道 FPS 與影格總數,tl.seek(seconds)通常更直接。 - 不要使用
requestAnimationFrame: 不要為了 GSAP 自行建立 rAF 迴圈。讓 Helios 透過subscribe來驅動更新。
原始碼檔案
- 範例:
examples/gsap-animation/