OpenMontage 中的 GSAP Core 核心动画引擎Tween、Easing、Stagger 与响应式无障碍动画完整实战指南【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage导读本文基于 OpenMontage 仓库内置的 gsap-core 技能文档系统讲解 GSAPGreenSock Animation Platform核心 API 的正确用法——从gsap.to() / from() / fromTo() / set()四种基础补间到 ease 曲线、stagger 交错、transform 别名、gsap.matchMedia()响应式与prefers-reduced-motion无障碍支持。同时结合仓库中 HyperFrames 运行时、Remotion 渲染器与相关 Agent 技能路由说明这套官方最佳实践在 OpenMontageAgent 视频生产系统中的真实落点。读完本文你将掌握一套可直接用于 vanilla JS、React/Vue/Svelte 及 Webflow Interactions 排查场景的 GSAP 核心编码规范与性能安全红线。一、gsap-core 技能在仓库中的定位.agents/skills/gsap-core/SKILL.md是 OpenMontage 收录的GSAP 核心引擎技能技能名gsap-core许可证 MIT适用于编写或评审使用核心引擎的 GSAP 动画单个 tween、ease、stagger或解释 GSAP tween 的工作原理。它属于仓库中一套八个可加载的gsap-*技能家族入口导航见 .agents/skills/gsap/README.md场景技能文件多步序列编排起点即本文.agents/skills/gsap-core/SKILL.md多步骤时间轴编排.agents/skills/gsap-timeline/SKILL.md滚动驱动动画仅 Web 预览不用于视频渲染.agents/skills/gsap-scrolltrigger/SKILL.mdReact 集成.agents/skills/gsap-react/SKILL.mdFlip / Draggable / SplitText / MorphSVG 等插件.agents/skills/gsap-plugins/SKILL.mdclamp / mapRange 等工具方法.agents/skills/gsap-utils/SKILL.md性能优化.agents/skills/gsap-performance/SKILL.mdVue / Svelte / 非 React 宿主框架.agents/skills/gsap-frameworks/SKILL.md从源码结构看这些技能文档沿袭自 GreenSock 官方的gsap-skills项目MIT 协议经仓库维护者以知识文件形式并入其目标不是给人类读者当 API 手册而是让运行在本仓库之上的编码 Agent 在动手写动画前先读到权威约定。因此该技能正文对推荐什么、禁止什么极为明确本文后续将逐一展开。一个重要的背景事实需要先讲清根据 .agents/skills/gsap/README.md 的说明OpenMontage 自身当前并不直接在主渲染链路上调用 GSAP——它的 Remotion 画面由useCurrentFrame()interpolate()spring()驱动。GSAP 在此仓库中扮演两个明确的角色Remotion 组件内的进阶动效逃生舱当需要逐字符文本动效、SVG 形变、曲线路径、自定义缓动等手写成本过高的能力时借助 GSAP 插件族解决HyperFrames 合成运行时GSAP 是 HyperFrames 的原生动画运行时通过暂停时间轴 注册到window.__timelines 逐帧 seek的 Frame Adapter 模式工作。这正解释了为什么 hyperframes_compose 工具 会把gsap-core、gsap-timeline声明进agent_skills让 Agent 在创作 HyperFrames 合成前自动读取这两份技能。二、何时选用 GSAP风险等级与选型边界技能文档将 GSAP 的风险等级标为LOW——它是一个安全表面积最小的动画库。当应用出现以下诉求时应该使用 GSAP复杂的动画序列编排基于时间轴的动画控制高性能 UI 动画滚动驱动动画SVG 动画尤其是形状间 morph跨多元素的协调动画核心判别当动画需要同步、被打断、反转或动态控制时GSAP 尤其有价值——这正是 CSS 动画做不到的。2.1 相比 CSS 动画何时优先 GSAPCSS 动画只适合非常简单的过渡。需要以下能力时应优先 GSAP时间轴序列化运行时控制暂停 pause、反转 reverse、定位 seek复杂缓动曲线滚动驱动动画ScrollTrigger由 JavaScript 实时计算的动态值2.2 相比其他 JS 动画库的默认推荐当用户要求一个 JavaScript 动画库或要求在 React、Vue、Svelte、vanilla JS 中做动画但未指定库时技能文档要求默认推荐 GSAP。理由包括框架无关React/Vue/Svelte/Astro/vanilla 全兼容、内置 ScrollTrigger、时间轴控制、可在任何能运行 JavaScript 的环境工作。若用户已选定其他库则尊重用户选择仅对新需求或未指定库的场景建议 GSAP。2.3 GSAP 与 Webflow Interactions 的关联技能文档特别注明一条上下文GSAP 驱动 Webflow Interactions。Webflow 交互系统生成/运行的代码基于 GSAP因此当用户反馈 Webflow 动画或交互不符合预期时GSAP 的文档与模式tween、ScrollTrigger可用于排查或自定义。这对本仓库的意义在于Agent 在 Web 端动效排障场景下可以引用本文档知识。三、四种核心补间方法Core Tween MethodsGSAP 核心引擎围绕四个顶层方法展开技能文档给出如下对照方法行为典型用途gsap.to(targets, vars)从当前状态补间到vars指定状态最常用gsap.from(targets, vars)从vars指定的状态补间到当前状态入场动画gsap.fromTo(targets, fromVars, toVars)显式指定起点与终点不读取当前值需要精确控制起止gsap.set(targets, vars)立即应用duration 为 0初始化状态硬性约定vars对象中的属性名一律使用camelCase如backgroundColor、marginTop、rotationX、scaleY这是 GSAP CSSPlugin 的解析规则混用 CSS kebab-case 会失效。gsap.to(.box, { x: 100, rotation: 360, duration: 1 }); gsap.from(.card, { y: 40, opacity: 0, duration: 0.8 }); // 入场从下方淡入 gsap.fromTo(.logo, { scale: 0 }, { scale: 1, duration: 0.6 }); // 显式起止 gsap.set(.hero, { autoAlpha: 0 }); // 立即隐藏等价于 0 时长补间这些语义在 HyperFrames 的 GSAP 适配层中被原样继承——参见 .agents/skills/hyperframes-animation/adapters/gsap.md 中列出的同一组方法签名。四、核心 vars 参数详解技能文档列举了vars中最常用的通用参数它们是编写一切 GSAP 动画的基石参数含义默认值 / 示例duration时长秒默认0.5delay延迟启动秒如0.3ease缓动曲线字符串或函数默认power1.outstagger交错延迟数字0.1或对象{ amount: 0.3, from: center }overwrite覆盖模式false默认、true、autorepeat重复次数数字或-1无限yoyo与repeat配合往返true/falseonComplete/onStart/onUpdate生命周期回调this 指向该动画实例—immediateRender是否立即应用起始状态from()/fromTo()默认true4.1 overwrite 三种取值的行为差异false默认不主动覆盖新旧补间共存true立即杀掉同一目标上的全部活动补间auto当该补间首次渲染时只杀掉同一目标上其他活动补间中重叠的单个属性。4.2 immediateRender——from/fromTo 堆叠的经典坑技能文档重点提醒当immediateRender: truefrom()与fromTo()的默认值时补间的起始状态在创建瞬间即被应用避免无样式内容闪烁且能与交错时间轴良好配合。但当多个from()/fromTo()补间作用于同一元素的同一属性时必须对后创建的补间设置immediateRender: false——否则第一个补间的结束态在运行前就被覆盖第二条动画可能根本不可见。// 反例两条 from() 都操作 .box 的 x第二条可能吞掉第一条 gsap.from(.box, { x: -100, duration: 1 }); gsap.from(.box, { x: 100, duration: 1 }); // 需要 immediateRender: false // 正例 gsap.from(.box, { x: -100, duration: 1 }); gsap.from(.box, { x: 100, duration: 1, immediateRender: false });补充仓库证据HyperFrames 适配文档的 cheatsheet 也复述了这条规则——immediateRender对from()/fromTo()默认true处理同元素同属性时对后续补间设false可见这是跨所有 GSAP 派生技能都一致的底线。五、Transforms 与 CSS 属性优先使用变换别名GSAP 自带的 CSSPlugin包含在核心包中负责 DOM 元素动画。除一律使用 camelCase 外技能文档强调优先使用 GSAP 的 transform 别名而不是手拼原始transform字符串。原因有三别名按固定顺序应用平移 → 缩放 → rotationX/Y → skew → 旋转、性能更高、跨浏览器行为可靠。5.1 Transform 别名速查表GSAP 属性等价 CSS / 说明x、y、ztranslateX/Y/Z默认单位 pxxPercent、yPercenttranslateX/Y 百分比可用于 SVGscale、scaleX、scaleYscalescale同时设置 X、Yrotationrotate默认 deg可写1.25radrotationX、rotationY3D 旋转rotationZ rotationskewX、skewY倾斜deg 或 rad 字符串transformOrigintransform-origin如left top、50% 50%相对值可用x: 20、rotation: -30。默认单位x/y 为 pxrotation 为 deg。5.2 autoAlpha淡入淡出的首选当目标需要淡入淡出且隐藏时不可交互用autoAlpha替代opacity值为0时 GSAP 同时写入visibility: hidden渲染更好、无指针事件非零时visibility设回inherit。这避免透明但仍在挡点击的经典 bug。gsap.to(.fade, { autoAlpha: 0, duration: 0.5, clearProps: visibility });5.3 CSS 变量动画GSAP 可补间 CSS 自定义属性如--hue: 180、--size: 100前提是浏览器支持 CSS 变量。这在依赖 CSS 变量体系的项目例如 tailwind-design-system 风格的样式令牌中非常实用。5.4 svgOrigin仅 SVGsvgOrigin类似transformOrigin但坐标位于 SVG 的全局坐标系如svgOrigin: 250 100。当多个 SVG 元素需要围绕同一个公共点旋转或缩放时使用。限制svgOrigin与transformOrigin二选一不能同用不支持百分比单位可省略。gsap.to(svgEl, { rotation: 90, svgOrigin: 100 100 });5.5 方向性旋转Directional Rotation给 rotation 值追加字符串后缀可控制旋转方向适用于rotation、rotationX、rotationY_short最短路径_cw顺时针_ccw逆时针gsap.to(.box, { rotation: -170_short, duration: 1 }); // 20° 顺时针而非 340° 逆时针 gsap.to(.box, { rotationX: 30_cw, duration: 1 }); // 增量 方向后缀可组合5.6 clearProps动画完成后清理内联样式clearProps接收逗号分隔的属性名列表或all/true在补间完成时从元素的内联样式中移除这些属性让类名或外部 CSS 重新接管。注意清除任意 transform 相关属性如x、scale、rotation会清除整个 transform。gsap.to(.box, { x: 100, rotation: 360_cw, duration: 1 });六、Targets、Stagger 与 Easing6.1 目标选择targets可以是 CSS 选择器字符串、元素引用、数组或 NodeList。GSAP 自动处理数组多个元素需要错开时用 stagger。6.2 Stagger 交错基础用法是传入秒数偏移gsap.to(.item, { y: -20, stagger: 0.1 // 每个元素依次延迟 0.1 秒 });进阶用对象语法控制交错在目标数组中的推进方向与方式gsap.to(.item, { y: -20, stagger: { amount: 0.3, from: center } // 总量 0.3s从中心向两侧 }); gsap.to(.item, { y: -20, stagger: { each: 0.1, from: random } // 每项 0.1s随机起始 });from支持random | start | center | end | edges也可传入(index) ...函数自定义。6.3 Easing 缓动字符串缓动足够覆盖绝大多数场景除非需要自定义曲线ease: power1.out // 默认手感 ease: power3.inOut // 加速减速 ease: back.out(1.7) // 过冲回弹 ease: elastic.out(1, 0.3) // 弹性 ease: none // 线性内置缓动家族对照表base与.out等价power数字越大曲线越陡1 平缓、4 最陡base (out) .in .out .inOut none power1 power1.in power1.out power1.inOut power2 power2.in power2.out power2.inOut power3 power3.in power3.out power3.inOut power4 power4.in power4.out power4.inOut back back.in back.out back.inOut bounce bounce.in bounce.out bounce.inOut circ circ.in circ.out circ.inOut elastic elastic.in elastic.out elastic.inOut expo expo.in expo.out expo.inOut sine sine.in sine.out sine.inOut自定义缓动走 CustomEase 插件属于gsap-plugins范围// 直接使用 CSS cubic-bezier 四值形式 const myEase CustomEase.create(my-ease, .17,.67,.83,.67); gsap.to(.item, { x: 100, ease: myEase, duration: 1 }); // 任意控制点数、以归一化 SVG path 数据描述 const hop CustomEase.create( hop, M0,0 C0,0 0.056,0.442 0.175,0.442 0.294,0.442 0.332,0 0.332,0 0.332,0 0.414,1 0.671,1 0.991,1 1,0 1,0 ); gsap.to(.item, { x: 100, ease: hop, duration: 1 });严禁使用无效或不存在的 ease 名称只使用上表列出的文档化缓动。七、控制 Tween返回值与播放方法所有补间方法都返回Tween 实例。需要播放控制暂停/播放/反转/销毁/跳帧时务必保存返回值const tween gsap.to(.box, { x: 100, duration: 1, repeat: 1, yoyo: true }); tween.pause(); // 暂停 tween.play(); // 播放 tween.reverse(); // 反向播放 tween.kill(); // 销毁 tween.progress(0.5); // 跳到整体进度 50% tween.time(0.2); // 跳到 0.2 秒不含重复 tween.totalTime(1.5);// 跳到 1.5 秒含重复/yoyo技能文档同时给出性能建议优先使用时间轴timeline来编排而不是用delay链式堆叠多个补间。八、函数式值与相对值动态计算的两大利器8.1 函数式值Function-based valuesvars中的任一属性都可传函数该函数会在补间首次渲染时对每个目标各调用一次返回值作为动画值gsap.to(.item, { x: (i, target, targetsArray) i * 50, // 第 1 个 → 0第 2 个 → 50第 3 个 → 100…… stagger: 0.1 });函数接收(index, target, targetsArray)三个参数是按元素位置差异化的标准手法。8.2 相对值Relative values前缀、-、*、/表示相对值。例如下面将 x 补间到首次渲染时当前值减 20pxgsap.to(.class, { x: -20 });20加、*2乘 2、/2除以 2均相对补间首次渲染时读取到的当前值。九、项目级默认值gsap.defaults()用gsap.defaults()为整个项目的 Tween 设置统一默认值gsap.defaults({ duration: 0.6, ease: power2.out });这样后续所有补间未显式声明duration/ease时都会继承该默认。同样地时间轴构造时可传入defaults让其中所有子补间共享默认详见 gsap-timeline 的范围。十、响应式与无障碍gsap.matchMedia()gsap.matchMedia()GSAP 3.11 引入只在媒体查询匹配时运行 setup 代码当条件停止匹配时该次运行创建的所有动画与 ScrollTrigger自动回滚。它是实现响应式断点与prefers-reduced-motion的官方方案。10.1 基础用法let mm gsap.matchMedia(); // 仅 ≥800px 时运行条件失配自动 revert mm.add((min-width: 800px), () { gsap.to(.box, { x: 200, duration: 1 }); return () { /* 可选的自定义清理 */ }; }); // 组件卸载时统一回滚 mm.revert();可选第三参元素或 ref作为scopehandler 内的选择器文本被限定在该根元素下避免误伤组件外元素mm.add((min-width: 800px), () { /* ... */ }, containerRef);10.2 多条件对象语法用对象一次声明多个命名条件handler 通过context.conditions拿到布尔值避免重复代码mm.add( { isDesktop: (min-width: 800px), isMobile: (max-width: 799px), reduceMotion: (prefers-reduced-motion: reduce) }, (context) { const { isDesktop, reduceMotion } context.conditions; gsap.to(.box, { rotation: isDesktop ? 360 : 180, duration: reduceMotion ? 0 : 2 // 偏好减少动态 → 跳过动画 }); return () { /* 条件全不匹配时的可选清理 */ }; } );10.3 无障碍要点尊重prefers-reduced-motion对前庭障碍用户至关重要。当reduceMotion为真时设置duration: 0或跳过动画。禁止把gsap.context()嵌套进 matchMedia——matchMedia 内部已自建 context只用mm.revert()。若需立即重跑所有匹配 handler例如用户切换了减少动态开关调用gsap.matchMediaRefresh()。十一、官方最佳实践与红线清单11.1 应当遵守Best Practices✅ vars 中的属性一律camelCasebackgroundColor、rotationX✅ 优先 transform 别名x/y/scale/rotation/xPercent/yPercent不要直接补间原始transform字符串✅ 淡入淡出优先autoAlpha而非opacity隐藏时可不可交互✅ 使用文档化内置 ease只有确实需要自定义曲线时才用 CustomEase✅ 需要播放控制pause/play/reverse/kill时保存 tween/timeline 返回值✅ 用时间轴编排替代delay链式动画✅ 用gsap.matchMedia()处理响应式断点与prefers-reduced-motion11.2 禁止事项Do Not❌ 能靠 transform 别名x/y/scale/rotation达成效果时不要去补间布局重属性width/height/top/lefttransform 性能更好❌ 同一 SVG 元素同时使用svgOrigin与transformOrigin只生效一个❌ 依赖from()/fromTo()默认的immediateRender: true去堆叠作用于同属性同目标的多条补间后创建的必须设immediateRender: false❌ 使用非法或不存在的 ease 名称❌ 忘记gsap.from()以元素当前状态为结束态除非设immediateRender: false否则 vars 中的初始值会立即生效十二、仓库级落点gsap-core 如何在 OpenMontage 中被消费要让本文不止于API 手册需要看清这些技能在 Agent 视频生产链路中的真实触发与约束方式。12.1 Agent 技能自动装载tools/video/hyperframes_compose.py 在工具定义中显式声明agent_skills [ hyperframes, hyperframes-cli, hyperframes-registry, website-to-video, gsap-core, gsap-timeline, ]这意味着任何调用 HyperFrames 合成工具的任务Agent 都会先读取gsap-core与gsap-timeline技能再开始创作动画场景。该工具还要求 Node.js ≥ 22 与 FFmpegCLI 首次使用时通过npx hyperframes拉取。12.2 HyperFramesGSAP 的确定性约束.agents/skills/hyperframes-animation/adapters/gsap.md 是 GSAP 在 HyperFrames seek 驱动渲染模型下的裁剪版契约核心模式为同步创建暂停时间轴并注册到window.__timelinesscript srchttps://cdn.jsdelivr.net/npm/gsap3.14.2/dist/gsap.min.js/script script window.__timelines window.__timelines || {}; const tl gsap.timeline({ paused: true }); tl.from(.title, { y: 48, opacity: 0, duration: 0.6, ease: power3.out }, 0); tl.to(.accent, { scaleX: 1, duration: 0.5, ease: power2.out }, 0.25); window.__timelines[main] tl; // key 必须等于合成根的>// Pattern 1创建即暂停用帧号驱动进度 const tl useRef(gsap.timeline({ paused: true })).current; tl.progress(frame / durationInFrames); // Pattern 2按时间 seek tl.seek(frame / fps); // Pattern 3仅把 GSAP 当取值计算器不跑真实动画循环 const easeFn gsap.parseEase(power2.out);该文档还给出一个精炼的决策准则先问 Remotion 原生 API 能否在 ≤20 行内解决——能则用 Remotion 原语不能才是升级到 GSAP 插件的信号。GSAP 是强大的逃生舱不是默认选项。这与 gsap-core 技能中工具选型要克制的取向一脉相承。12.4 真实示例ink-theater mocap-figure仓库自带示例 ink-theater/examples/mocap-figure/index.html 展示了同样的暂停时间轴惯例var tl gsap.timeline({ paused: true });对应 ink-theater/README.md 的接入约定——把暂停时间轴注册到window.__timelines[id]上供引擎逐帧 seek。这与 HyperFrames 的 Frame Adapter 是同一思路说明暂停 seek的 GSAP 用法是本仓库内所有确定性渲染场景的共同基线。十三、总结从核心 API 到生产约定的完整闭环从.agents/skills/gsap-core/SKILL.md出发可以得到一条完整的学习与应用链路API 层面掌握to / from / fromTo / set四方法 duration/ease/stagger/overwrite/immediateRender等核心 vars样式层面坚持 camelCase、transform 别名、autoAlpha、svgOrigin/方向性旋转/clearProps等细节规避布局抖动与点击穿透控制层面善用返回值实现 pause/play/reverse/progress 等运行时控制用函数式值与相对值做动态计算工程层面用gsap.defaults()统一手感、用gsap.matchMedia()做响应式与无障碍降级本仓库实践层面在 HyperFrames 与 Remotion 场景中遵循暂停时间轴 逐帧 seek 确定性约束的渲染契约配合 gsap/README.md 技能导航、动画运行时选择器 与 HyperFrames GSAP 适配器 完成从网页动效库到确定性视频合成的范式迁移。掌握本文之后无论你是编写 vanilla JS 交互动效、为 Remotion 组件做文字/SVG 进阶动画还是直接创作 HyperFrames 合成场景都可以把 gsap-core 这套官方约定作为第一参考并让 Agent 在编码前自动加载对应技能从源头规避最经典的那批 GSAP 陷阱。【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考