HyperFrames 关键帧
关键帧是一种姿态合约:可见状态、连续的物体身份、安全寻帧的运行时、经过验证的像素。
使用 hyperframes-animation 获取宏观场景方案。使用 hyperframes-cli 获取完整的命令文档。仅在实现机制不明确时,才使用 references/keyframe-patterns.md 来指导选择,而非用于视觉样式决策。
流程
- 确定动画主体、可见状态、最终状态和运行时长。
- 选择能证明提示需求的最小机制。如果机制不明确,才阅读
references/keyframe-patterns.md。 - 在声明运行时长内编写安全寻帧的关键帧。同步构建并注册运行时实例。
- 使用
hyperframes lint、hyperframes check、hyperframes keyframes、一个聚焦的--shot以及在证明时间点的快照进行验证。 - 如果验证失败,则修复源关键帧,并在渲染前重新运行最小的失败诊断。
合约
- 命名移动主体。
- 命名证明预期运动所需的姿态,包括最终状态。
- 关键帧应对可见通道进行动画,而非隐藏辅助状态。
- 当连续性重要时,保持物体身份。
- 仅当预期动作为替换或溶解时,才使用交叉淡入淡出。
- 保持可读或语义状态足够长的时间以便被看到。
- 最终帧是动画的一部分,不是清理步骤。
- 除非要求,否则不要重置到静止状态。
- 除非要求,否则不要以黑色结束。
- 如果编辑初始场景,除非要求重新设计,否则应保留布局、文案、资源、颜色和最终状态。
运行时规则
GSAP:
- 在页面加载时同步构建
- 使用
gsap.timeline({ paused: true }) - 注册为
window.__timelines[compositionId] - 注册键必须匹配
data-composition-id - 不要为渲染关键动画调用
tl.play() - 保持有限迭代
CSS 关键帧:
- 有限持续时间和迭代次数
- 确定性延迟
animation-fill-mode: both- 当时序属于某个片段时,使用
data-start
Anime.js:
- 同步创建
autoplay: false- 有限持续时间和循环次数
- 将所有实例推送到
window.__hfAnime
WAAPI:
- 有限
duration fill: "both"- 确定性构造
- 文本表面不列出 WAAPI;使用
--shot(它可查找 WAAPI)和快照验证
永远不要在渲染关键动画中使用:
Date.now()performance.now()- 未设种子的
Math.random() - 悬停/滚动触发器
- 定时器
- 异步创建的时间线
- 未注册的
requestAnimationFrame - 无限循环
GSAP 骨架
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
使用标签表示语义状态。使用位置参数而不是链式延迟。为后来操作同一属性的 from()/fromTo() 补间设置 immediateRender: false。
关键帧形式
- 数组关键帧:带逐步骤持续时间和缓动函数的姿态阶梯。
- 百分比关键帧:单个补间内的精确时序。
- 属性数组:紧凑的多步变化。
- 当每一步携带自身的缓动函数时,父级设置
ease: "none"。 - 当每个片段应共享相同感觉时使用
easeEach。
不要从示例中复制数字距离或时序。根据实际合成的几何图形和持续时间推导它们。
对于一个在两个盒子之间移动的物体,首选一个连续的变换补间或 FLIP。仅当希望观众感受不同的节拍时,才将 x/y/scale 拆分为多个带缓动的关键帧;每个片段都会改变速度,可能被感知为卡顿。
通道
首选合成器/视觉通道:x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、蒙版、CSS 变量、SVG 路径/描边值、相机变换、着色器统一变量。
避免使用布局/生命周期通道:top/left/right/bottom、width/height、margin/padding、display、visibility、后期 DOM 创建、执行物体运动的辅助覆盖层。
对于可见性变化,在已注册的可寻帧 GSAP 时间线上使用 autoAlpha,或在显式边界处使用零持续时间的 tl.set()。目标选择非片段元素或片段内的包装器;永远不要定位 .clip 本身。永远不要对原始 visibility 进行补间动画,也永远不要对 display 进行补间动画。
机制选择
选择能证明提示需求的最小机制:
| 需求 | 机制 |
|---|---|
| 同一主体变换盒子或层级 | 共享元素 / FLIP |
| 主体沿可见路径移动 | 路径运动 |
| 描边生长或追踪 | 描边绘制 |
| 一个形状变为另一个形状 | 形状插值 |
| 揭示边界可见 | 裁剪、蒙版或着色器统一变量 |
| 许多物体按顺序移动 | 交错 / 索引延迟 |
| 文本自身移动 | 行、词、字符或带细分 |
| 表面弯曲、拉伸或裁剪 | 父/子级反向变换 |
| UI 有状态 | 显式状态机 |
| 场景有深度 | DOM 3D、Three.js 或 WebGL 相机/物体关键帧 |
机制可以组合,但每个机制必须阐明思想。装饰不是证明。
时序
- 仅在能阐明原因或方向时使用预备动作。
- 加速意味着从静止开始。
- 峰值证明必须明确展示机制。
- 随动传达能量和方向。
- 仅当主体应感觉有弹性或触感时才使用过冲。
- 匀速路径运动通常需要
ease: "none"。 - 离散 UI 状态通常需要锐利的缓出。
- 重复元素需要有序偏移,而非相同时序。
- 最终锁定需要比过渡姿态更长的保持时间。
- 平滑意味着同一主体上的连续速度。
- 除非有意且已验证,否则不要重叠写入相同变换属性的补间。
- 避免在主要表面同时缩放或移动时,动画大型
clip-path/蒙版变化;在主移动稳定后再使用嵌套揭示。
文字
保留行框、字间距、可读性和最终适配。如果文本内部移动,则移动字形或遮罩带,而不仅仅是文本周围的装饰。对可读帧进行快照。
SVG
对于描边生长,优先使用 DrawSVGPlugin,然后是 stroke-dasharray/stroke-dashoffset。对于形状插值,优先使用 MorphSVGPlugin;必要时将基本形状转换为路径,并将复杂轮廓拆分为更简单的部分。
3D
单独的缩放是虚假深度。在稳定的父级上使用透视、transform-style: preserve-3d、z 轴移动、旋转、相机/世界运动、遮挡以及物体交叉时的层顺序。
使用一到两个能暴露深度关系的诊断角度。如果角度证明未显示深度交叉,则改进 z 轴/相机/遮挡。
画布 / WebGL
通过确定性状态对相机位置、相机目标、物体变换、材质透明度、着色器统一变量和后处理强度进行关键帧动画。从 HyperFrames 时间渲染。使用 --ghost,因为标记框无法看到内部画布运动。
CLI 验证
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
为真实的动画主体选择 <selector>。为第一帧、证明姿态、最终-保持和精确最终选择 <times>。仅在需要证明深度时选择 <angle>。
| 工具 | 证明范围 |
|---|---|
keyframes | 目标、显式停止点、路径、轨迹、组合的父/子级运动、CSS 停止点、Anime 注册 |
--shot | 幽灵、路径形状、时间间隔、DOM 3D 投影、聚焦选择器验证 |
--layout strip | 原地运动、重叠、接触、细微缩放/透明度、文字波动 |
--ghost | 画布、WebGL、着色器运动、渲染的 3D |
snapshot --at | 蒙版、文字可读性、完整状态、最终锁定、黑色/重置尾迹 |
如果选择器验证结果看起来错误:
- 重新运行
--json - 找到实际的动画目标
- 对该目标进行截图
- 对完整帧进行快照
- 信任渲染的像素胜过日志
诊断解读
flat 意味着没有明确的中间姿态。keyframes 意味着存在显式停止点。motionPath 意味着存在路径。trace 意味着多笔描画。composed with 意味着子运动继承父运动。
幽灵间距均匀意味着速度恒定。幽灵聚集意味着慢入或稳定。大间距意味着快速移动。
辅助选择器截图不是证据。在破碎的完整帧上叠加洋葱皮截图不是证据。
错误处理
| 失败情况 | 修复方法 |
|---|---|
| 仅端点存在 | 添加中间姿态,保持峰值证明,重新运行 --shot |
| 身份中断 | 保持一个元素存活,使用共享源/最终框,移除替代交叉淡入淡出 |
| 虚假 3D | 添加 z 轴/相机移动、遮挡、角度验证。 |
| 最终状态错误 | 添加最终保持,对最终-保持和精确最终进行快照。 |
| 不可寻帧的运行时 | 暂停自动播放,注册实例,移除定时器,同步构建。 |
| 文字不可读 | 保留行框,减少位移,添加最终保持,对文字帧进行快照。 |
完成
运行 hyperframes lint、hyperframes check、hyperframes keyframes、一个聚焦的 --shot 和快照。确认第一帧、证明姿态、最终-保持、精确最终、主体拥有的运动,并且没有调试覆盖层。