OpenMontage HyperFrames 动画实践：GSAP 变换属性别名与渲染性能优化指南

HyperFrames 是一个把 HTML 当作视频源来渲染的动画系统：每个分镜（composition）只维护一条暂停的 GSAP 时间线，交给渲染器逐帧 seek，从而保证确定性输出。在 OpenMontage 的 .agents/skills/hyperframes-animation 技能库中，gsap-transforms-and-perf.md 是 GSAP 适配器三件套（timeline、easing/stagger、transforms/perf）的第三篇，聚焦「动什么」与「怎么动才快」。本文将该文档展开成一份可复制的实战指南：先厘清变换别名的语义，再逐个讲透 autoAlpha、clearProps、CSS 变量、相对值与 SVG 细节，最后落到渲染性能规则上，并结合本仓库的技能契约、CLI 验证命令与相邻文档，说明每一条规则在 HyperFrames 确定性渲染模型下的底层原因。

先看这份文档在技能库中的位置

在 hyperframes-animation/SKILL.md 的路由表里，GSAP 相关的查询被拆成了四份适配器文档：

想解决什么	看哪份文档
GSAP 时间线 / tween / 位置参数 API	adapters/gsap.md
变换属性 / autoAlpha / 性能	adapters/gsap-transforms-and-perf.md
缓动 / stagger / 函数式数值	adapters/gsap-easing-and-stagger.md
时间线 / 标签 / 嵌套	adapters/gsap-timeline-and-labels.md

SKILL 同时写明：GSAP 是 HyperFrames 95% 动效工作的默认运行时，技能库中的全部原子规则（rules/）都以 GSAP 编写。也就是说，transform 别名与性能规则不只是一份「建议」，而是编写任何一条可复用动效规则（rules/*.md）前都必须先内化的地基。它还与 hyperframes-core/SKILL.md 的「可动属性白名单」直接对应——白名单规定只允许动画合成器廉价的属性（opacity、x、y、scale*、rotation*、skew* 等）与视觉填充类属性（color、backgroundColor、borderColor、borderRadius），这正是本文「prefer transforms」主张的契约化来源。

Transform Aliases：让 GSAP 逐轴跟踪，避免补间互相覆盖

文档给出的第一张表是「用别名、别写裸 transform 字符串」的完整对照：

GSAP 属性	等价的 CSS
x, y, z	translateX/Y/Z（px）
xPercent, yPercent	translateX/Y（%）
scale, scaleX, scaleY	scale
rotation	rotate（deg）
rotationX, rotationY	3D rotate
skewX, skewY	skew
transformOrigin	transform-origin

关键收益在原文档一句话点破：别名让 GSAP 能够对每个轴独立跟踪与插值，从而避免同一元素上多个独立 tween 之间的意外互相覆盖。假设两条 tween 同时（或先后）作用于同一元素——一条想动 x、另一条想动 rotation，若直接操作合并后的 transform 字符串，第二条会整段覆盖第一条解析出的变换矩阵；而使用别名后，GSAP 把 x 与 rotation 视为正交通道，各自插值、最后合成。

这在 HyperFrames 里还有一重特殊含义。核心契约（见 hyperframes-core 与 adapters/gsap.md）规定空间运动只允许用 transform 别名：x、y、scale、rotation；非空间属性才允许 opacity/color/backgroundColor/borderRadius；而 width/height/top/left 这类触发布局回流（layout reflow）的属性被明确列入 Avoid。所以别名不只是编码风格，而是与渲染器逐帧并行采样这一工作模式配套的硬约束：tween 时刻去量 getBoundingClientRect() 会因并行采样而失步（SKILL 的 Critical Constraints 中对此有专门警告），正确做法是在构图 setup 阶段一次性算好坐标常量，之后全靠别名驱动。

另一个相关点：属性名一律用 camelCase（如 backgroundColor、rotationX），这与 CSS 连字符写法在 GSAP 中不通用——adapters/gsap.md 的最佳实践里明确要求。

autoAlpha：把「透明」做成「接近消失」

显示/隐藏类动效，优先用 autoAlpha 而不是裸 opacity：

gsap.to(".panel", { autoAlpha: 0, duration: 0.4 });

autoAlpha: 0 会同时设置 opacity: 0 与 visibility: hidden。这比纯 opacity: 0 更接近「gone」：透明度为 0 但 visibility: visible 的元素仍然参与命中测试、仍留在可访问性树中，可能挡住点击、被读屏软件读出；而 visibility: hidden 会让元素从这两者中移出。

注意它与 HyperFrames 契约的配合方式：在 adapters/gsap.md 的 Forbidden 清单里，display、visibility 被禁止作为直接 tween 目标——因为这些是离散属性、无法平滑插值，且会干扰渲染器的生命周期。而 autoAlpha 是特例：它只在端点处同步设置 opacity 与 visibility，不对离散属性本身做逐帧补间，因此在白名单内是推荐替代方案。对应地，在 hyperframes-core 的非协商规则 中也能看到「绝不 tween display / visibility」的同一条禁令，可见这是贯穿整个技能体系的一致红线。

clearProps：补间结束后把元素交还给 CSS

gsap.to(".item", { x: 100, rotation: 45, clearProps: "all" });
gsap.to(".item", { x: 100, rotation: 45, clearProps: "rotation,x" });

clearProps 会在补间完成时移除 GSAP 写入的内联样式，可选值为 "all"（清掉本补间设置的所有属性）或逗号分隔的指定属性列表。典型场景是一个动效段落收尾后，把元素的状态交还给 CSS——后续的 hover、响应式布局或由样式表控制的静态呈现不再被遗留的内联 transform 绑架。

给这两个示例补充两个使用要点（依据在 adapters/gsap.md 的 cheatsheet）：

• clearProps 通常配合 onComplete 或时间线末位使用，且要与 overwrite 策略一起考虑：默认 overwrite: false，若后续 tween 目标同一元素同属性，可能需要在时间线内显式控制顺序或用 "auto" 清理冲突。
• 在 HyperFrames 中，如需让元素「在某个时间点之后恢复 CSS 姿态」，把它放进单条暂停时间线里用位置参数调度（如 tl.to(..., ..., "+=1.2")），而不是另起炉灶去叠延迟，详见 gsap-timeline-and-labels.md。

CSS Variables：直接动画化自定义属性

gsap.to(".chart", { "--hue": 180, duration: 1 });

GSAP 可以把任何自定义属性当作 tween 目标，颜色、长度、数字均可——只要 CSS 自己能插值，GSAP 就能动。这在数据可视化、图表着色、主题切换类场景尤其好用：把 --hue 这类单一变量作为「总开关」，一行动画带动整个色板渐变。这一点与 hyperframes-core 的属性白名单也相容——白名单中明确放行 "--hue": 180 这类 CSS 变量补间。

相对值与方向性旋转

文档列出两类高级值语法：

• 相对值："+=20"、"-=10"、"*=2"——在当前位置基础上增量/倍数移动，适合不知道起始值的场景。
• 方向性旋转："360_cw"、"-170_short"、"90_ccw"——控制角度在两点之间绕哪边、走多远。默认 GSAP 会选最短路径；当你想明确顺时针一整圈、或强制走长弧线时，就用这些后缀。

其中 360_cw 这类「显式绕圈」在 HyperFrames 中要特别注意与核心契约配合：SKILL 与 adapters/gsap.md 都禁止 repeat: -1 等无限循环（渲染输出的是有限时长的视频），需要无限旋转感时应按可见时长换算成有限次数，例如一圈 1.2s、场景 6s 就 repeat: 4，配合 yoyo 与方向性旋转实现持续但可定长的旋转。

SVG Specifics：svgOrigin 的坐标系陷阱

• svgOrigin 把变换原点设在 SVG 全局坐标空间里，而不是元素自身的局部盒（local box）。同一个元素上绝不能同时使用 svgOrigin 和 transformOrigin——两者坐标系与语义不同，叠加会得到难以预测的变换；文档明确要求「pick one」。adapters/gsap.md 的 Do Not 清单也复述了这条禁令。
• 动画化 SVG 的 transform 属性时，直接复用同一套别名（x、y、rotation），SVG 特有的坐标系怪癖由 GSAP 自行处理，不需要手写 transform="translate(...) rotate(...)" 字符串。

经验补充：当目标是让某个 SVG 元素绕 SVG 画布中的某一点（而非自身中心）公转/摆动时，优先用 svgOrigin；绕自身中心缩放或翻转时用 transformOrigin。做选择前先想清楚「原点相对谁」，就不会踩到两个属性同时出现导致的静默错位。

性能规则：把动画压进 GPU 合成层

优先 transform 与 opacity

x、y、scale、rotation、opacity 的动画停留在 GPU 合成器（compositor） 上，不触发 layout 与 paint；而 width、height、top、left、margin、padding 会引发布局回流。凡是能用 transform 达成相同视觉效果（移动、缩放、展开）的，就不要动布局属性。

这条规则在 HyperFrames 中不是「最好遵守」，而是「必须遵守」：adapters/gsap.md 的 Avoid 段把 width/height/top/left/right/bottom/margin*/padding* 全部列为禁区，并给出替代方案——横向生长用 scaleX（配合 transformOrigin 控制生长方向），位移用 x/y。渲染器需要以固定分辨率逐帧采样同一份 DOM，任何一次中途触发的回流都可能造成帧间布局抖动，因此在源头禁掉布局属性是保证画面稳定的前提。

will-change：只在真正动起来的元素上用

.title {
  will-change: transform;
}

will-change 只是「提前声明」某个属性会被频繁修改，好让浏览器预先把它提升到合成层。文档的措辞很克制：只加在真正会动画化的元素上。到处滥用会让浏览器为大量元素各开合成层，白白烧掉内存，甚至比不加更慢。合理用法是动画即将开始时加、结束后移除，或至少保持数量级可控——大多数 HyperFrames 场景里，动效集中在标题、卡片、指示器上，覆盖这几个关键元素即可。

gsap.quickTo：高频事件更新的首选（仅限预览）

鼠标移动、滚动、音频 scrub 这类事件驱动的高频更新里，与其每帧 new 一个 tween，不如用 quickTo 复用同一条 tween：

const xTo = gsap.quickTo("#cursor", "x", { duration: 0.4, ease: "power3" });
const yTo = gsap.quickTo("#cursor", "y", { duration: 0.4, ease: "power3" });

container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

这里必须强调一个 HyperFrames 独有的关键限制（原文档用引用块专门标注）：

Render mode has no input events. 渲染器是逐帧 seek 的，mousemove、scroll 等事件永远不会触发。quickTo 的主战场只在浏览器里的实时预览（live preview）。渲染模式下若要做「音频响应」动效，正确姿势是预先抽取音频数据，再以声明方式驱动时间线（见 rules/gsap-effects.md）。

这条注释是整个技能体系「确定性优先」哲学的缩影：预览可以自由响应输入，但渲染路径必须只依赖时间。具体到音频可视化，rules/gsap-effects.md 给出的工作流是先用仓库里的抽取脚本把音频转成 JSON 帧数据（命令形态如 python .../scripts/extract-audio-data.py audio.mp3 -o audio-data.json，脚本本体位于 hyperframes-creative/scripts/extract-audio-data.py），再为每一帧注册一个 tl.call(...)，用 frame.rms 与 frame.bands 驱动 Canvas/DOM——渲染时不用 Web Audio API，因为 seek 过程中根本没有播放。注意加载数据要用内联或同步 XHR，不能用异步 fetch()：HyperFrames 在页面加载后同步读取 window.__timelines，把时间线构建放进 .then() 意味着捕获开始时时间线还没就绪。

Stagger 胜过 N 条补间

用一条带 stagger 的补间，好过 N 条手动加 delay 的补间——无论可读性还是运行时开销都是。进一步说（细节在 gsap-easing-and-stagger.md）：stagger 支持对象形态，可控制 each（每条间隔）、from（"start" | "end" | "center" | "edges"，甚至指定索引）、amount（总时长，设置后覆盖 each）、grid（2D 网格 stagger）与 axis；当目标数量或顺序变化时，stagger 依然保持正确，而手写延迟列表必然要跟着改。文档还建议用 fromTo() 而非 from()，让起始状态显式可读（这也是子构图入场的一致约定）。

gsap.fromTo(
  ".item",
  { y: 24, opacity: 0 },
  { y: 0, opacity: 1, duration: 0.5, stagger: { each: 0.08, from: "center" } },
);

Cleanup：离屏即暂停

在实时预览中，暂停或 kill() 掉屏幕外（不可见区域）的动画，省下无谓的逐帧计算。渲染模式不受影响——渲染器直接驱动时间，离屏动画同样会被精确采样，清理操作不会改变成片内容。这条规则再次印证了预览与渲染是两套执行模型：预览优化针对浏览器空闲成本，而渲染的正确性始终由「单一暂停时间线 + 时间驱动」保证。

收尾：把规则放进验证闭环

把本文所有规则落实后，可以用技能库配套的命令做体检（命令一览见 hyperframes-animation/SKILL.md 的 See Also 与 hyperframes-core 的 Validation 清单）：

npx hyperframes lint        # 0 errors
npx hyperframes validate    # 0 console errors
npx hyperframes inspect     # 0 errors
npx hyperframes preview     # 交用户审阅
npx hyperframes render      # 用户批准后再出片

需要注意的是（在 hyperframes-core/SKILL.md 中反复强调）：布局塌陷、gsap.set 提前命中后续场景元素、超范围属性动画等静默 bug，lint/validate/inspect 不一定抓得到，最终防线仍是作者遵循本文与 gsap.md、hyperframes-core 确定性规则 的约定去写。

综上，这份 transforms-and-perf 文档提供的是一套「先选对属性，再谈性能」的完整决策路径：SVG 认准坐标系、显示隐藏用 autoAlpha、收尾用 clearProps、整体只动合成器廉价属性、高频输入只在预览用 quickTo、成组动效用 stagger、渲染期一律走声明式时间驱动。在 HyperFrames 的确定性渲染模型下，这套规则的每一环都不是可有可无的性能提示，而是保证「预览所见即渲染所得」的必要条件。需要更完整的上下文时，可顺着 adapters/gsap.md → gsap-timeline-and-labels.md / gsap-easing-and-stagger.md 继续深入。