OpenMontage 中的 GSAP Core 核心动画引擎：Tween、Easing、Stagger 与响应式无障碍动画完整实战指南

导读

本文基于 OpenMontage 仓库内置的 gsap-core 技能文档，系统讲解 GSAP（GreenSock Animation Platform）核心 API 的正确用法——从 gsap.to() / from() / fromTo() / set() 四种基础补间，到 ease 曲线、stagger 交错、transform 别名、gsap.matchMedia() 响应式与 prefers-reduced-motion 无障碍支持。同时结合仓库中 HyperFrames 运行时、Remotion 渲染器与相关 Agent 技能路由，说明这套官方最佳实践在 OpenMontage"Agent 视频生产系统"中的真实落点。读完本文，你将掌握一套可直接用于 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.md
React 集成	.agents/skills/gsap-react/SKILL.md
Flip / Draggable / SplitText / MorphSVG 等插件	.agents/skills/gsap-plugins/SKILL.md
clamp / mapRange 等工具方法	.agents/skills/gsap-utils/SKILL.md
性能优化	.agents/skills/gsap-performance/SKILL.md
Vue / 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 在此仓库中扮演两个明确的角色：

1. Remotion 组件内的进阶动效逃生舱：当需要逐字符文本动效、SVG 形变、曲线路径、自定义缓动等手写成本过高的能力时，借助 GSAP 插件族解决；
2. 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 动画何时优先 GSAP

CSS 动画只适合非常简单的过渡。需要以下能力时应优先 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 Methods）

GSAP 核心引擎围绕四个顶层方法展开，技能文档给出如下对照：

方法	行为	典型用途
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.5
delay	延迟启动（秒）	如 0.3
ease	缓动曲线，字符串或函数	默认 "power1.out"
stagger	交错延迟	数字 0.1 或对象 { amount: 0.3, from: "center" }
overwrite	覆盖模式	false（默认）、true、"auto"
repeat	重复次数	数字或 -1（无限）
yoyo	与 repeat 配合往返	true / false
onComplete / onStart / onUpdate	生命周期回调，this 指向该动画实例	—
immediateRender	是否立即应用起始状态	from()/fromTo() 默认 true

4.1 overwrite 三种取值的行为差异

• false（默认）：不主动覆盖，新旧补间共存；
• true：立即杀掉同一目标上的全部活动补间；
• "auto"：当该补间首次渲染时，只杀掉同一目标上其他活动补间中重叠的单个属性。

4.2 immediateRender——from/fromTo 堆叠的经典坑

技能文档重点提醒：当 immediateRender: true（from() 与 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、z	translateX/Y/Z（默认单位 px）
xPercent、yPercent	translateX/Y 百分比，可用于 SVG
scale、scaleX、scaleY	scale；scale 同时设置 X、Y
rotation	rotate（默认 deg，可写 "1.25rad"）
rotationX、rotationY	3D 旋转（rotationZ = rotation）
skewX、skewY	倾斜（deg 或 rad 字符串）
transformOrigin	transform-origin（如 "left top"、"50% 50%"）

相对值可用：x: "+=20"、rotation: "-=30"。默认单位：x/y 为 px，rotation 为 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（仅 SVG）

svgOrigin 类似 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 与 Easing

6.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 values）

vars 中的任一属性都可传函数：该函数会在补间首次渲染时对每个目标各调用一次，返回值作为动画值：

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 补间到"首次渲染时当前值减 20px"：

gsap.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）作为 scope：handler 内的选择器文本被限定在该根元素下，避免误伤组件外元素：

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 中的属性一律 camelCase（backgroundColor、rotationX）
• ✅ 优先 transform 别名（x/y/scale/rotation/xPercent/yPercent），不要直接补间原始 transform 字符串
• ✅ 淡入淡出优先 autoAlpha 而非 opacity（隐藏时可不可交互）
• ✅ 使用文档化内置 ease；只有确实需要自定义曲线时才用 CustomEase
• ✅ 需要播放控制（pause/play/reverse/kill）时保存 tween/timeline 返回值
• ✅ 用时间轴编排替代 delay 链式动画
• ✅ 用 gsap.matchMedia() 处理响应式断点与 prefers-reduced-motion

11.2 禁止事项（Do Not）

• ❌ 能靠 transform 别名（x/y/scale/rotation）达成效果时，不要去补间布局重属性（width/height/top/left），transform 性能更好
• ❌ 同一 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 与 FFmpeg，CLI 首次使用时通过 npx hyperframes 拉取。

12.2 HyperFrames：GSAP 的确定性约束

.agents/skills/hyperframes-animation/adapters/gsap.md 是 GSAP 在 HyperFrames "seek 驱动渲染模型"下的裁剪版契约，核心模式为同步创建暂停时间轴并注册到 window.__timelines：

<script src="https://cdn.jsdelivr.net/npm/gsap@3.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 必须等于合成根的 data-composition-id
</script>

适配文档同时收紧了 gsap-core 的通用规则：渲染关键动效不得调用 tl.play()；禁止在异步代码/timer/事件 handler 内建时间轴；禁止 repeat: -1 无限重复（视频时长必须有限，用可见时长反推有限 repeat 次数）；动画属性只允许动效合成器廉价属性（opacity、x/y/scale/rotation/skew、transformOrigin、颜色类、CSS 变量、媒体 volume、文本计数器 innerText）；display/visibility 严禁直接补间（用 autoAlpha），任何依赖 Math.random()/Date.now() 的动画都被禁止，以保证逐帧渲染确定性。这条"视频渲染必须确定性"的约束同样出现在 skills/core/hyperframes.md 的若干 Do Not 清单中。

12.3 在 Remotion 中的确定性用法

标准 GSAP 走 requestAnimationFrame 驱动，对 Remotion 逐帧渲染不确定。仓库的技能路由文档 skills/meta/animation-runtime-selector.md 给出了三种 Remotion-safe 模式：

// 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 出发，可以得到一条完整的学习与应用链路：

1. API 层面：掌握 to / from / fromTo / set 四方法 + duration/ease/stagger/overwrite/immediateRender 等核心 vars；
2. 样式层面：坚持 camelCase、transform 别名、autoAlpha、svgOrigin/方向性旋转/clearProps 等细节，规避布局抖动与点击穿透；
3. 控制层面：善用返回值实现 pause/play/reverse/progress 等运行时控制，用函数式值与相对值做动态计算；
4. 工程层面：用 gsap.defaults() 统一手感、用 gsap.matchMedia() 做响应式与无障碍降级；
5. 本仓库实践层面：在 HyperFrames 与 Remotion 场景中遵循"暂停时间轴 + 逐帧 seek + 确定性约束"的渲染契约，配合 gsap/README.md 技能导航、动画运行时选择器 与 HyperFrames GSAP 适配器 完成从"网页动效库"到"确定性视频合成"的范式迁移。

掌握本文之后，无论你是编写 vanilla JS 交互动效、为 Remotion 组件做文字/SVG 进阶动画，还是直接创作 HyperFrames 合成场景，都可以把 gsap-core 这套官方约定作为第一参考，并让 Agent 在编码前自动加载对应技能，从源头规避最经典的那批 GSAP 陷阱。