HyperFrames GSAP 动画开发指南：用暂停时间线构建确定性视频合成
【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes
HyperFrames 以 HTML 描述视频合成，并把动画运行时交给 GreenSock（GSAP）。在这套体系里，你负责编排动画本身，而播放头、时间推进与逐帧渲染完全由 HyperFrames 运行时接管——本指南围绕 packages/cli/src/docs/gsap.md 的约定，讲解如何编写一套可被运行时精确 seek、可被渲染器逐帧消费的 GSAP 时间线。读完你将掌握：加载与注册时间线的标准写法、window.__timelines注册表契约、必须遵守的暂停/定位/取值规则、渲染安全的属性子集，以及时间线在运行时内部被绑定与驱动的底层机制。
为什么动画必须是一根“被暂停”的 GSAP 时间线
HyperFrames 的渲染模型不是浏览器里自然播放，而是把合成当作一根可以定位到任意帧的时间线：预览播放器与渲染引擎都会对时间线执行seek/totalTime，让某一秒（通常是 30fps 量化后的帧时刻）的 DOM 状态落定，再截取画面。
因此 HyperFrames 对动画的约定非常明确：
- 用 GSAP 创建时间线，但必须
{ paused: true }，不允许它靠自身的 ticker 自主推进； - 把创建好的时间线挂到
window.__timelines上，以合成 ID 为键； - 之后时间线的推进、暂停、seek 完全由 HyperFrames 运行时控制。
这段设计在源码中随处可见。运行时把全局注册表声明为__timelines: Record<string, RuntimeTimelineLike>（见 packages/core/src/runtime/window.d.ts），RuntimeTimelineLike则要求时间线具备play/pause/seek/totalTime/progress/time/duration/paused等确定性控制面（见 packages/core/src/runtime/types.ts）。GSAP 时间线恰好原生实现这些方法，这也是它能成为首选动画运行时的直接原因。
最小可运行骨架：从加载 GSAP 到注册时间线
原文档给出的 Setup 是所有合成的基础模板，直接按此结构编写：
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script> <script> const tl = gsap.timeline({ paused: true }); tl.to("#title", { opacity: 1, duration: 0.5 }, 0); window.__timelines = window.__timelines || {}; window.__timelines["root"] = tl; </script>把它放进一个完整合成里，还需要根元素的若干数据属性来声明画幅、时长与合成 ID。仓库内置模板 packages/cli/src/templates/blank/index.html 给出了权威样板（data-composition-id="main"与注册键"main"对应）：
<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=1920, height=1080" /> <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script> </head> <body> <div id="root" ><div>npx hyperframes lint ./my-composition npx hyperframes lint ./my-composition --verbose # 显示 info 级提示 npx hyperframes render -c ./my-composition.html -o output.mp4其中lint会加载@hyperframes/parsers/gsap-parser-acorn对脚本做真正的静态解析（lint 规则对“解析器无法解析目标”的元素会保守跳过，避免误报，见 packages/lint/src/rules/gsap.ts 顶部实现），从而给出比“肉眼检查”更接近渲染器视角的诊断。渲染参数（--fps、--quality、--workers等）的完整说明见 packages/cli/src/docs/rendering.md。
起步模板与更多示例
npx hyperframes init my-video会基于内置模板脚手架项目。其中blank模板就是一个“空 1920×1080 合成 + 已接好 GSAP 暂停时间线”的起点，title-card模板则示范了用 GSAP 做标题淡入淡出的完整套路（模板清单见 packages/cli/src/docs/examples.md）。GSAP 动画涉及 Studio 关键帧编辑、确定性渲染等更多主题时，可继续阅读同仓库文档树中的相关章节继续深入。
核心要点回顾：paused 时间线 + 按合成 ID 注册 + 绝对时间定位 + 只动受支持属性 + 把可见性与媒体交给运行时，这五件事做到了，你的 GSAP 合成就能在预览与正式渲染之间稳定复现同一段运动。
【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
