使用指南
GSAP 动画
使用 GSAP 为 Hyperframes 合成添加动画。
Hyperframes 使用 GSAP 进行动画。时间线是暂停的，由运行时控制——你定义动画，框架处理播放。有关动画运行时如何接入 Hyperframes 的背景，请参见帧适配器。
设置
包含 GSAP 并创建暂停的时间线：
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 1. 创建暂停的时间线——框架控制播放
const tl = gsap.timeline({ paused: true });
// 2. 使用位置参数（第 3 个参数）进行绝对计时
l.to("#title", { opacity: 1, duration: 0.5 }, 0);
// 3. 初始化全局时间线注册表（如果尚未存在）
window.__timelines = window.__timelines || {};
// 4. 使用 data-composition-id 作为键注册时间线
window.__timelines["root"] = tl;
</script>
ℹ️ Note
你在
window.__timelines中使用的键必须与合成根元素上的data-composition-id属性匹配。参见合成了解根元素的结构。
关键规则
- 始终使用
{ paused: true }创建时间线 — 框架通过确定性搜索控制播放 - 在
window.__timelines上注册时间线，使用data-composition-id作为键 - 使用位置参数（第 3 个参数）进行绝对计时：
tl.to(el, vars, 1.5) - 只对视觉属性做动画 — 永远不要在脚本中控制媒体播放
支持的方法
| 方法 | 描述 |
|---|---|
tl.to(target, vars, position) | 动画到指定值 |
tl.from(target, vars, position) | 从指定值动画 |
tl.fromTo(target, fromVars, toVars, position) | 从/到指定值动画 |
tl.set(target, vars, position) | 立即设置值 |
支持的属性
opacity、x、y、scale、scaleX、scaleY、rotation、width、height、visibility、color、backgroundColor，以及任何 CSS 可动画属性。
时间线时长与合成时长
合成的时长等于其 GSAP 时间线时长。两者直接关联：
// 你的最后一个动画在 3 秒结束...
l.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
l.to("#title", { opacity: 0, duration: 1 }, 2);
// ...所以这个合成恰好是 3 秒长。
如果你的合成包含一个 283 秒长的视频片段，但你的最后一个 GSAP 动画在 8 秒结束，合成将只有 8 秒长，视频会被截短。要延长时间线以匹配视频：
// 你所有的视觉动画
l.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);
// 将时间线延长到 283 秒以匹配视频长度。
// 这在 283s 添加一个零时长的补间，不影响任何元素。
l.set({}, {}, 283);
⚠️ Warning
这是 Hyperframes 中最常见的错误之一。如果你的视频提前截断，时间线太短了。参见常见错误：合成时长短于视频了解更多详情。
不应该做什么
这些模式会破坏你的合成或导致同步问题：
// 错误：在脚本中播放媒体——框架拥有媒体播放权
document.getElementById("el-video").play();
document.getElementById("el-audio").currentTime = 5;
// 错误：创建非暂停的时间线
const tl = gsap.timeline(); // 缺少 { paused: true }！
// 错误：直接对 <video> 元素的尺寸做动画
l.to("#el-video", { width: 500, height: 280 }, 5);
// 错误：手动嵌套子时间线
const masterTL = window.__timelines["root"];
masterTL.add(window.__timelines["intro-anim"], 0);
框架自动管理媒体播放、clip 生命周期和子合成嵌套。复制此行为的脚本会产生冲突。
子合成时间线
每个嵌套合成注册自己的时间线。框架根据 data-start 自动将子合成时间线嵌套到父时间线中：
// 在 compositions/intro-anim.html 中
const tl = gsap.timeline({ paused: true });
l.from(".title", { opacity: 0, y: -50, duration: 1 });
window.__timelines["intro-anim"] = tl;
// 不要手动将子时间线添加到主时间线：
// masterTL.add(window.__timelines["intro-anim"], 0); // 不需要
⚠️ Warning
不要直接对
<video>元素的width、height、top或left做动画——这可能导致浏览器停止渲染帧。将视频包装在<div>中并对其包装器做动画。参见常见错误了解详细解释。
下一步
- 合成 理解时间线动画的构建块
- 帧适配器 了解 GSAP 如何接入渲染管线
- 常见错误 避免破坏动画的陷阱
- HTML Schema 参考 合成属性的完整参考