插件安装: 在执行设置或 freshness 命令之前,当此技能位于 HyperFrames 插件内部时,请遵循 插件执行规则。独立安装则保留下面的更新说明。
HyperFrames 关键帧 是做什么的?
关键帧是一种姿态契约:可见状态、连续主体身份、安全可寻的运行时间、经过验证的像素。
对于宏观场景配方,请使用 hyperframes-animation。对于完整命令文档,请使用 hyperframes-cli。仅在选择实现机制(而非视觉风格)时,才使用 references/keyframe-patterns.md。
创作者编辑边界
关键帧负责视觉运动,而非剪辑组装。源范围硬切、修剪、拼接和重新排序属于 /hyperframes-core:每个保留范围为创作一个媒体元素,使用 data-start 和 data-duration 放置,并用 data-media-start 选择其源偏移量。相邻范围形成硬切。交叉淡入淡出使用不同轨道上的重叠剪辑加上视觉透明度关键帧;音频淡入淡出使用 /hyperframes-audio。
| 创作者请求 | 真实机制 |
|---|---|
| 推拉(Punch-in / punch-out) | 在剪辑内部非时间控制的视觉/裁剪包装器上,对 scale 以及 x/y 或百分比平移进行关键帧动画。对于硬推拉使用 set/short tween,对于平滑移动使用 tween。 |
| 平滑多状态缩放或重构图 | 保持一个主体包装器存活,并将多个缩放/重构图状态编写为带有每段缓动的姿态阶梯。 |
| 平移、重构图或 Ken Burns 摄像机运动 | 对包装器平移和缩放进行动画。几何是创作出来的;这不是人脸追踪或自动语义重构图。 |
| 链式摄像机运动 | 在一个注册的安全可寻时间线上,链式编写带标签的变换节拍。 |
| 匹配剪辑或甩镜头 | /hyperframes-animation 负责视觉交接;/hyperframes-registry 提供基本元素;关键帧保留创作的几何、方向和速度。没有自动匹配帧的发现。 |
| 裁剪和蒙版重构图 | 在内部视觉包装器上对 clip-path 或蒙版进行插值,以在不改变源时间的情况下裁剪/重构图。多边形关键帧可以形成多边形/蒙版过渡。 |
| 方向性擦除剪辑或光圈/揭示剪辑 | 在重叠的视觉剪辑上对蒙版/clip 边界进行动画;/hyperframes-animation 负责交接编排。 |
| 分屏交接 | 保持两个视觉剪辑由核心放置,然后对其内部裁剪/蒙版包装器和分隔线几何进行关键帧动画。 |
| 恒定源重定时 | /hyperframes-core 拥有标准化 data-playback-rate(0.1..10),用于渲染安全的图像和保持音高的声音。它对整个媒体元素是恒定的。 |
| 源速度斜坡 | <video>/<audio> 上 data-automation 中的 rate 通道(t 以剪辑秒为单位,v 0.1..10,对数插值);它覆盖恒定速率。 |
| 冻结 / 保持 | 一个视觉姿态、最终源帧或完成的子合成可以保持。不支持任意的中途源冻结;预处理一个静态/衍生片段,将其作为自己的剪辑放置,然后用另一个源范围恢复。 |
在同时编辑画面和声音时,加载 /hyperframes-core、此技能用于视觉运动,以及 /hyperframes-audio 用于淡入淡出、交叉淡入淡出、音量自动化、闪避/雕刻或对已放置轨道的效果。
视觉过渡或裁剪处理不是时间的源修剪或拼接。/hyperframes-core 拥有时间线、剪辑时序和源范围;关键帧仅对那些剪辑内部包装器上的可见交接或裁剪进行动画。对于可复制的组合画面/声音配方,请使用 /hyperframes-core → references/creator-editing-recipes.md。
步骤
- 确定被动画的主体、可见状态、最终状态和运行时间。
- 选择能证明提示的最小机制。只有在机制不清晰时才阅读
references/keyframe-patterns.md。 - 在声明的运行时间内创作安全可寻的关键帧。仅在构建完成后注册运行时实例;在
document.fonts.ready内部构建是可以的。 - 使用
hyperframes check(运行 lint)、hyperframes keyframes、一个集中的--shot以及在验证时刻的截图进行验证。 - 如果验证失败,修复源关键帧并在渲染前重新运行最小的失败诊断。
契约
- 命名正在运动的主体。
- 命名证明预期运动所需的姿态,包括最终状态。
- 对可见通道进行关键帧,而不是隐藏的辅助状态。
- 当连续性重要时保持对象身份。
- 仅当预期运动是替换或溶解时才使用交叉淡入淡出。
- 将可读或语义状态保持足够长的时间以便看到。
- 最终帧是动画的一部分,而非清理。
- 除非被要求,否则不要重置到静止状态。
- 除非被要求,否则不要以黑屏结束。
- 如果编辑一个起始场景,除非被要求重新设计,否则保留布局、副本、资源、颜色和最终状态。
运行时规则
GSAP:
- 在页面加载时或
document.fonts.ready内部构建,且仅在构建完成后注册 - 使用
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() tween 使用 immediateRender: false。
关键帧形式
- 数组关键帧:带有每步持续/缓动的姿态阶梯。
- 百分比关键帧:一个 tween 内部的确切时序。
- 属性数组:紧凑的多停靠点变化。
- 当每个停靠点都有自己的缓动时,父级使用
ease: "none"。 - 当每个片段应共享相同感觉时使用
easeEach。
不要从示例中复制数字距离或时序。从实际合成几何和持续时间中推导它们。
对于在两个框之间移动的一个主体,优先使用一个连续的变换 tween 或 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 进行持续时间 tween,也绝不要对 display 进行 tween。
机制选择
选择能证明提示的最小机制:
| 需求 | 机制 |
|---|---|
| 同一主体更改盒子或层级 | 共享元素 / FLIP |
| 主体沿可见路线运动 | 路径运动 |
| 笔画生长或勾勒 | 笔画绘制 |
| 形状变为另一个形状 | 形状插值 |
| 揭示边界是可见的 | clip、蒙版或着色器统一变量 |
| 许多项目按顺序运动 | 交错 / 索引延迟 |
| 文本本身运动 | 行、词、字符或带划分 |
| 表面弯曲、拉伸或裁剪 | 父/子计数器变换 |
| UI 有状态 | 显式状态机 |
| 场景有深度 | DOM 3D、Three.js 或 WebGL 摄像机/对象关键帧 |
机制可以组合,但每个机制必须澄清想法。装饰不是证明。
时序
- 仅当它澄清原因或方向时才使用预计。
- 加速度离开静止。
- 峰值证明明确无误地显示机制。
- 后续动作传达能量和方向。
- 仅当主体应感觉有弹性或触感时才使用过冲。
- 恒速路径运动通常需要
ease: "none"。 - 离散 UI 状态通常需要锐利的缓出。
- 重复的元素需要有序的偏移,而不是相同的时序。
- 最终锁定需要比过渡姿态更长的保持。
- 平滑意味着同一主体上的连续速度。
- 不要重叠写入相同变换属性的 tween,除非有意且经过验证。
- 避免在同一个英雄表面也正在缩放或移动时动画大量
clip-path/蒙版变化;在主移动稳定后使用嵌套揭示。
文本
保留行框、词间距、可读性和最终适配。如果文本内部移动,移动字形或遮罩带,而不仅仅是文本周围的装饰。对可读帧进行截图。
SVG
对于笔画生长,优先使用 DrawSVGPlugin,然后使用 stroke-dasharray/stroke-dashoffset。对于形状插值,优先使用 MorphSVGPlugin;需要时将基本形状转换为路径,并将复杂轮廓拆分为更简单的部分。
3D
仅缩放是伪深度。在稳定父级上使用透视、transform-style: preserve-3d、z 轴运动、旋转、摄像机/世界运动、遮挡以及当对象交叉时的图层顺序。
使用一个或两个能暴露深度关系的诊断角度。如果角度证明未显示深度交叉,改进 z/摄像机/遮挡。
Canvas / WebGL
通过确定性状态对摄像机位置、摄像机目标、对象变换、材质透明度、着色器统一变量和后期处理强度进行关键帧。从 HyperFrames 时间渲染。使用 --ghost,因为标记框无法看到内部 Canvas 运动。
CLI 证明
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 | Canvas、WebGL、着色器运动、渲染的 3D |
snapshot --at | 蒙版 |
…
[为翻译截断]