gsap-animation-composition

GSAP 动画编排

当媒体合成需要的动画编排难以用彼此独立的 CSS 过渡或简单的帧间插值表达时，请使用 GSAP：例如重叠的多节拍序列、逐字符排版、SVG 描边绘制或形状变形、曲线路径、布局状态过渡，或由同一播放头控制的可复用运动语言。

本技能涵盖 GSAP 作为媒体制作中的动画引擎。它不能取代宿主渲染器的合成约定、剪辑决策、音频时间线、素材清单、无障碍审核或交付工作流。

依据与版本说明

全文使用以下标签：

• 文档事实：官方 GSAP、W3C 或浏览器文档中明确说明的行为。
• 制作经验法则：实用的默认做法，但应以项目需求、品牌规范、渲染器或实测结果为准。
• 实测观察：在实际合成、预览、渲染或目标设备上测得的结果。

GSAP API、插件打包方式、许可和框架集成经常变化。以下 API 和许可信息已于 2026-07-12 核实。投入生产前，请重新检查已安装的 GSAP 版本、官方安装指南、插件文档和当前许可。

判断是否需要 GSAP

如果以下任一项是交付内容的核心需求，请选择 GSAP：

• 许多相互依赖的动画节拍需要共享标签、重叠关系或嵌套时间线；
• 文本需要拆分为单词、行或字符，以实现精心设计的呈现效果；
• SVG 路径需要绘制、变形或承载移动对象；
• 布局变化需要通过 FLIP 过渡保持视觉上的连贯性；
• 基于浏览器的合成需要一个可定位的统一播放头，用于预览和帧捕获；
• 响应式版本需要相关但差异显著的动画编排。

以下情况优先考虑更简单的机制：

• 只有一个元素需要淡入淡出、平移、缩放或旋转；
• 宿主视频运行时已提供简洁的帧间插值或弹簧动画原语；
• 常规剪辑、合成或关键帧更便于接手团队修改；
• 交付内容是静态图像、交换格式素材，或不会在浏览器环境中运行的原生应用动画。

不要仅仅因为插件存在就添加它。每个插件都应能显著降低实现风险，或改善预期的动画效果。

明确动画约定

编写动画代码前，请记录：

• 合成尺寸、宽高比、帧率和时长；
• 场景和节拍的时间码，包括音频或旁白锚点；
• 准确的屏幕文字和最终定格状态；
• 图层名称、选择器、SVG 路径 ID 和变换轴心；
• 每个动画元素的入场、强调、过渡和退场目的；
• 动画设计变量：时长类别、缓动类别、错开策略、移动范围和过冲策略；
• 响应式版本和减少动态效果版本；
• 播放头的控制方；
• 插件导入和当前许可审核；
• 审核帧和失败阈值。

如果渲染器会捕获任意帧，那么无论按什么顺序访问帧，合成都必须正确。实时预览再精美，也不能证明渲染具有确定性。

构建一个受控时间轴

**文档说明：**GSAP 的 Timeline 包含补间和嵌套时间轴，并可将它们作为一个整体进行控制。其位置参数可将子项放置在绝对时间、相对于时间轴末尾、相对于标签，或相对于最近添加的子项的位置，并可使用 < 和 > 等标记。时间轴提供 pause()、seek()、time()、progress() 和 totalProgress() 等控制方法。

使用语义化标签表示编辑节拍，而不是偶然的实现步骤：

const timeline = gsap.timeline({
  paused: true,
  defaults: {duration: 0.42, ease: "power3.out"},
});

timeline
  .addLabel("claim", 0.4)
  .from(".claim-line", {yPercent: 110, stagger: 0.07}, "claim")
  .addLabel("proof", "claim+=0.85")
  .from(".proof-mark", {scaleX: 0, transformOrigin: "left"}, "proof")
  .from(".proof-label", {opacity: 0, y: 16}, "<0.12")
  .to(".claim-group", {opacity: 0, duration: 0.24}, ">+1.1");

这只是示例，并非规定的时间轴结构。

生产规则：

• 当标签与脚本、音乐或剪辑事件对应时，使用 claim、proof、turn 和 cta 等标签。
• 使用时间轴默认值构建协调一致的动画风格，再有意地覆盖这些默认值。
• 按场景或语义单元嵌套时间轴；将它们返回到主时间轴。
• 优先使用位置参数，而不是手动计算延迟并串联。
• 为渲染媒体使用有限时间轴。无限重复没有可审核的最终状态。
• 当两个端点都必须明确时使用 fromTo()，尤其是在重新渲染、响应式重建或重复状态变化之后。其他情况下，优先使用更简单的 to() 或 from() 形式。
• 不要让 CSS 过渡与 GSAP 同时控制相同属性。
• 如果由 GSAP 控制变换属性，则应始终通过 GSAP 一致地设置变换状态。

交错动画

**文档说明：**GSAP 交错动画可以使用数值、对象或函数。对象配置可以通过 each 或总计 amount 分布开始时间、选择 from 起点、考虑网格、限制轴向，并缓动分布效果。

使用交错动画来表达层级、方向或节奏。不要用它来回避对单个节拍的设计。对于文本，最后一个单元出现后，应让最终短语保持足够长的可读时间。对于网格，应测试实际的响应式布局，而不要假设 DOM 顺序与视觉顺序一致。

确保帧捕获具有确定性

GSAP 的常规播放由浏览器动画循环驱动。文档说明：gsap.ticker 通过 requestAnimationFrame 更新全局时间轴；浏览器调度和隐藏标签页限流情况各不相同。因此，请求精确帧的视频渲染器应显式控制时间，而不是等待实际时间播放。

当宿主可以跳转已暂停的时间轴时，使用以下模式：

const timeline = buildTimeline();
timeline.pause(0);

export function renderAtFrame(frame, fps) {
  const time = frame / fps;
  timeline.time(Math.min(time, timeline.duration()), false);
}

如果宿主需要归一化进度：

timeline.totalProgress(frame / Math.max(1, totalFrames - 1), false);

渲染器专用集成可以使用其他适配器，但应保留以下不变量：

1. 在所需 DOM、字体、SVG 和本地资源准备就绪后，同步构建时间轴。
2. 在开始捕获前暂停时间轴。
3. 仅根据请求的帧和声明的 fps 推导时间。
4. 使用固定输入。为随机值设定种子或预先计算；不要在帧求值期间调用 Math.random()。
5. 不要将网络获取、一天中的时间、用户输入、滚动状态和异步回调用作动画状态。
6. 确保向后跳转时能恢复正确状态。
7. 确保回调副作用具有幂等性，或在任意跳转期间将其抑制。

不要将 gsap.ticker.fps(30) 与确定性的 30 fps 渲染混为一谈。它会限制 ticker 回调频率，但不会让浏览器调度成为帧渲染契约。

根据制作问题选择插件

仅注册实际构建中包含的插件，并使用当前软件包版本的官方安装模式。

制作问题	适用能力	主要审核风险
对单词、行或字符进行编排	SplitText	语义发生变化、换行错乱、缺少清理步骤、文本不再可访问
显示 SVG 描边	DrawSVG	路径长度错误、压缩后线条过细、最终状态缺乏意义
将一个 SVG 形状变形成另一个形状	MorphSVG	点对应关系不佳、自交、轮廓意外变化、源路径不兼容
沿路径移动或调整对象朝向	MotionPath	坐标空间错误、旋转异常、路径超出裁切范围、引起晕动
在测量后的布局状态间制作动画	Flip	测量结果过时、捕获期间发生重排、最终布局不明确
编码项目专属的运动曲线	CustomEase	曲线过度拟合或过于极端、命名不一致、加速度难以感知
将动画与页面滚动关联	ScrollTrigger	不适用于固定时长视频，除非将滚动转换为明确的时间轴进度

文本拆分

将拆分生成的包装层视为实现层，而非撰写的文案。在源文件中保留原文，并在目标交付形式中验证辅助技术的行为。拆分前应等待生产字体加载完成，因为换行和字形度量可能发生变化。响应式换行变化时，应重新构建并还原拆分后的文本。

对于固定的视频渲染，如果设计要求固定换行，应保存已批准的换行。不要让偶然的浏览器宽度决定主视觉文案。

SVG 描画、变形与路径

• 清理源路径并设置有意选择的 viewBox。
• 记录每个枢轴点和坐标系统。
• 在交付分辨率下检查起始、中间和最终轮廓。
• 让源形状和目标形状在语义上相关；变形应传达转变，而不只是展示技术上的新奇效果。
• 最终视频压缩后检查细线条。
• 对角色或对象绑定，围绕设定好的枢轴点为稳定的组制作动画，而不要独立变形每条路径。

FLIP 转场

捕获初始状态，应用最终布局，然后为测量出的差异制作动画。冻结数据和布局输入，以确保渲染结果可复现。如果最终状态取决于字体加载、网络数据或响应式测量，应先解决这些依赖，再记录状态。

响应式与减少动态效果的变体

文档说明：gsap.matchMedia() 可以针对原生媒体查询运行设置逻辑，在上下文中收集动画，并在条件不再匹配时还原。它可以组合宽度查询与 (prefers-reduced-motion: reduce)。

使用响应式变体来保留层级，而不是将桌面端编排硬塞进较小的画面。纵横比变化时，应调整换行、路径几何形状、移动距离、交错方向和标签时序。相关布局稳定后，再重新构建时间轴。

对于交互式交付，应尊重用户偏好，并在需要时提供控件。减少动态效果时，可以采用切换镜头、短暂淡入淡出、局部强调和稳定的最终状态，而不是大范围平移、视差、快速缩放或旋转。

对于预录制视频，导出后 prefers-reduced-motion 无法改变像素。应判断受众或发布目的地是否需要单独渲染减少动态效果的版本。

**文档说明：**WCAG 2.2 SC 2.3.3 规定，除非动画不可或缺，否则应允许禁用由交互触发的非必要动态效果动画。SC 2.3.1 要求内容在任意 1 秒内闪烁不得超过 3 次，除非其低于一般闪烁阈值和红色闪烁阈值。在最大预期呈现尺寸下测试渲染视频，并在循环播放时测试循环效果。

清理与框架生命周期

文档记载的事实： gsap.context() 可以收集在其函数内创建的动画、限定选择器的作用范围，并还原已收集的动画。gsap.matchMedia() 内部使用 context。还原操作会销毁已收集的动画，并恢复记录的动画前状态；自定义事件监听器仍需显式清理。

每个已挂载的合成或响应式状态只创建一次时间轴。拆卸时：

• 还原 context 或 match-media 对象；
• 移除自定义事件和 ticker 监听器；
• 还原拆分文本和临时包装元素；
• 释放特定渲染器的观察器；
• 清除对已从 DOM 或 SVG 分离的节点的引用。

在基于 React 的渲染器中，使用当前官方 GSAP React 集成，或生命周期安全的等效 effect。不要在每次渲染时实例化时间轴。

性能与渲染可靠性

生产环境的经验准则：

• 高频运动优先使用变换和不透明度；在假设其他属性不适用之前，先进行测量。
• 未进行性能分析前，避免在多层间为大面积模糊、滤镜、阴影或遮罩添加动画。
• SVG 路径复杂度应与输出分辨率相称。
• 预先创建稳定的时间轴，而不是在重复触发的交互回调中构建时间轴。
• 将选择器限定在合成根节点的范围内。
• 每个动画属性只由一个对象负责。
• 将远程资源固定为本地资源，并在捕获前等待字体加载完成。
• 提交长时间或高分辨率导出前，先渲染一小段压力测试片段。

记录实测结果：浏览器和 GSAP 版本、渲染器、GPU／软件路径、帧尺寸、fps、并发数、丢帧或重复帧、内存情况，以及预览和渲染之间的任何差异。

许可与权利审核关卡

包含此技能的仓库采用 MIT 许可。这不会改变 GSAP 的许可。

文档记载的事实，经 2026-07-12 核实： 当前官方页面指出，Webflow 的 Standard “No Charge” GSAP License 自 2025 年 4 月 30 日起生效，最后修改于 2025 年 5 月 30 日。该许可授予在获准的网站、Web 应用和数字界面实现中使用的权利，包括商业项目。未经同意，不得将其用于允许用户无需编写代码即可构建视觉动画的工具，若此类用途与 Webflow 的视觉动画构建功能构成竞争。该许可还限制为竞争产品进行逆向工程，以及移除专有声明。许可页面说明其内容可能更新，因此在生产环境中使用前应再次核查。

单独的 greensock/gsap-skills 文档仓库可能采用 MIT 许可；这不会改变 GSAP 运行时或插件的许可。不要根据文档源代码的许可推断运行时的使用权。

发布前：

• 确认由谁分发和运营该合成或工具；
• 核查当前 GSAP 许可和软件包声明；
• 对视觉动画构建器、编辑器产品、模板即服务、再许可、再分发或存在竞争关系且性质不明确的用途，咨询权利方或法律顾问；
• 保留软件包和部署要求的第三方声明；
• 分别核实字体、徽标、插画、SVG 美术作品、音乐、源媒体和肖像的权利。

这是生产风险指导，不构成法律建议。

审核与质量保证

按以下顺序审核作品：

1. 约定： 尺寸、帧率、时长、确切文案、获批素材、插件和许可状态。
2. 确定性： 在干净运行环境中捕获同一帧两次；比较场景边界和向后跳转的表现。
3. 时序： 确认标签与旁白、音乐和剪辑事件相符；确保结尾停留画面清晰可读。
4. 运动： 检查弧线、枢轴、变形轮廓、路径方向、FLIP 连贯性、缓动和过冲。
5. 排版： 确认字体已加载、换行正确、包装元素已清理、字形完整，且最终状态清晰可读。
6. 无障碍： 检查减少动态效果版本的交付、闪烁、大范围运动、文本对比度，以及仅通过运动传达的信息。
7. 性能： 对动态效果最强的片段和最终交付分辨率进行性能分析。
8. 输出： 检查抽帧画面和完整播放，确认没有画面裁切、素材缺失、图层冻结、压缩损坏或音画不同步。

严重问题包括：帧输出不确定、存在不安全的闪烁、交互界面缺少必要的减少动态效果处理、必需文本无法阅读、最终 SVG 轮廓损坏、使用未获许可的素材，或固定时间渲染所依赖的时间线受墙上时钟／滚动状态影响。

示例 1：动感新品发布主张

这是一个完整示例，并非强制套用的公式。

制作意图： 制作一段 6 秒的 9:16 产品发布插片，使用确切的品牌文案且不含旁白。首条主张必须快速呈现，证明内容必须保持清晰可读，并且需要提供减少动态效果的社交媒体版本。

输入与约束： 获批的字体文件；文案 Review less. Decide sooner.；1080x1920，30 fps；最终 CTA 锁定版式；禁止全屏闪烁；GSAP 和 SplitText 可在审查许可条款后使用。

计划：

00:00.00-00:00.35  Background and clipping masks already stable.
00:00.35-00:01.15  Split headline by words; reveal from lower mask with 0.07 s stagger.
00:01.15-00:02.20  Hold complete claim.
00:02.20-00:03.05  Draw proof underline; reveal source-safe proof label 0.12 s later.
00:03.05-00:04.45  Hold claim and proof without motion.
00:04.45-00:05.10  Exit claim as one group; do not scramble characters.
00:05.10-00:06.00  CTA lockup, static final state.

实施方向：

• 在拆分文本前加载确切的字体。
• 使用带有 claim、proof 和 cta 标签的暂停式 6 秒主时间线。
• 使用 frame / 30 驱动时间线时间。
• 保持源标题文本不变，并在拆除时还原 SplitText 包装元素。
• 减少动态效果的版本采用 0.18 秒的主张组淡入、直接切至证明内容，并保持相同的停留时长。

为何有效： 逐词错落呈现体现了句子的节奏，同时较长的证明内容停留时间有助于理解。确定性的播放头可让预览与渲染保持一致。

预期结果： 文案准确；多次捕获之间不改变换行；最终 CTA 稳定；重复渲染的帧保持一致。

可能的问题： 字体在文本拆分后才加载；字符错落效果导致阅读过慢；响应式重建后包装元素仍然残留；跳转时播放头回调触发两次；CTA 在退出动画结束前出现。

有意义的变化： 对于 16:9 画面，保留标签，但将垂直排列的词组改为两行，并缩短移动距离，而不是对垂直设计进行居中裁切。

示例 2：SVG 路线到标志的变形

这是一个完整示例，并非必须遵循的固定公式。

**制作意图：**制作一段 8 秒的说明性转场，让配送路线变为产品获批的标志，将流程说明衔接到品牌片尾卡。

**输入和限制：**获批的 SVG 路线和徽标路径；1920x1080，30 fps；低饱和度的海军蓝背景；不使用随机粒子；描边必须经得起 H.264 压缩；除获批的变形外，不得更改徽标几何形状。

工作流：

1. 将两个 SVG 规范化为一个经审核的 viewBox；仅简化冗余路径点，并存档原件。
2. 使用 DrawSVG 在 00:00.40 到 00:01.80 之间绘制路线。
3. 使用 MotionPath 让小包裹标记在 00:00.55 到 00:02.00 之间沿路线移动；禁用自动定向，因为包裹标签必须保持正向。
4. 完整路线保持 0.6 秒。
5. 在 00:02.60 到 00:03.55 之间，将获批的路线路径变形为获批的标志。
6. 平稳定格，不使用弹性过冲；显示字标，并将完整组合标志保持到 00:08.00。
7. 定位并检查第 0、12、30、54、78、92、107 和 239 帧，以及变形的中间帧。

**这样做的原因：**每个插件只负责一项语义任务：路线进度、包裹移动，然后变为品牌标识。延长片尾停留时间，便于将品牌标志用作剪辑点。

**预期结果：**包裹沿路径移动且不旋转；变形不会产生自相交；最终标志与获批的源图完全一致。

**可能的问题：**坐标系不一致；压缩后路径描边变得过细；变形对应关系形成扭结；标记偏出裁剪范围；最终形状与获批标志几乎一致，但并非完全一致。

**有意义的变体：**如果无法在不改变品牌几何形状的情况下实现路径的干净变形，则在共享轮廓处使用匹配剪辑或蒙版交叉淡化，不要强行使用 MorphSVG。

来源

已于 2026-07-12 查阅官方及权威来源：

• GSAP 时间轴文档：https://gsap.com/docs/v3/GSAP/Timeline/
• GSAP 交错动画指南：https://gsap.com/resources/getting-started/Staggers/
• GSAP context 和 matchMedia 文档：https://gsap.com/docs/v3/GSAP/gsap.context/ 和 https://gsap.com/docs/v3/GSAP/gsap.matchMedia/
• GSAP ticker 文档：https://gsap.com/docs/v3/GSAP/gsap.ticker/
• GSAP 插件文档：https://gsap.com/docs/v3/Plugins/
• GSAP CustomEase 文档：https://gsap.com/docs/v3/Eases/CustomEase/
• GSAP 常见错误：https://gsap.com/resources/mistakes/
• Webflow，《标准“免费”GSAP 许可证》：https://gsap.com/community/standard-license/
• W3C WCAG 2.2，《交互触发的动画》：https://www.w3.org/WAI/WCAG22/Understanding/animation-from-interactions.html
• W3C WCAG 2.2，《三次闪烁或低于阈值》：https://www.w3.org/WAI/WCAG22/Understanding/three-flashes-or-below-threshold.html
• MDN，prefers-reduced-motion：https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion