HyperFrames 动画
所有动效知识集中在此技能中:规则(原子配方)、蓝图(多阶段场景模板)、过渡(场景间切换)、技巧(更广泛的动效设计模式)和适配器(每个运行时的 API)。
关于合成合约(数据属性、子合成、确定性),请参阅 hyperframes-core。
默认方式:组合原子规则
从 rules-index.md 中选取 2-4 条规则,用一条暂停的 GSAP 时间线将它们粘合在一起,完成。这比从蓝图开始更快,生成的代码也更少。
何时加载蓝图
- 当场景与现有的预设计多阶段模板(如品牌展示、社交证明等)匹配,并且重用其阶段流水线确实可以节省创作时间时
- 当你需要为复杂的 4-5 阶段编排获取可运行的、可作为依据的代码时
蓝图位于 blueprints-index.md 中。每个条目指向 blueprints/<id>.md(配方)。不要投机性地读取它;只有在你已经确定需要场景级编排时才加载它。
导览
| 想要… | 阅读 |
|---|---|
| 根据触发器/标签选取一个原子动效模式 | rules-index.md |
| 阅读一条规则的完整 HTML / CSS / GSAP 配方 | rules/<name>.md |
| 选取一个多阶段场景模板 | blueprints-index.md |
| 读取一个蓝图的完整配方 | blueprints/<id>.md |
| 创作一个场景过渡(CSS 驱动,在两个片段之间) | transitions/overview.md, transitions/catalog.md |
| 查找一个更广泛的动效设计技巧 | techniques.md |
| 运动模糊——元素上的快门拖影,以及何时不使用它 | references/motion-blur.md |
| 分析现有合成的动画图表 | scripts/animation-map.mjs |
| GSAP API——时间线 / 补间动画 / 位置参数 | adapters/gsap.md |
| GSAP——即用型效果配方 | rules/gsap-effects.md |
| GSAP——变换 / 性能 | adapters/gsap-transforms-and-perf.md |
| GSAP——缓动 / 错开 | adapters/gsap-easing-and-stagger.md |
| GSAP——时间线 / 标签 | adapters/gsap-timeline-and-labels.md |
Lottie / dotLottie(After Effects 导出,window.__hfLottie) | adapters/lottie.md |
| 角色动画(行走循环、吉祥物、关节木偶、手势) | adapters/lottie.md → 角色 |
Three.js / WebGL(3D 场景,AnimationMixer,hf-seek) | adapters/three.md |
Anime.js(window.__hfAnime) | adapters/animejs.md |
CSS 关键帧(animation-delay / play-state / fill-mode) | adapters/css-animations.md |
Web Animations API(element.animate(),currentTime 跳转) | adapters/waapi.md |
TypeGPU / WebGPU(navigator.gpu,WGSL,计算管线) | adapters/typegpu.md |
将 HTML 作为纹理 + WebGL/GLSL 后期特效(通过 drawElementImage 捕获实时 DOM) | adapters/html-in-canvas-patterns.md |
命名文本动画效果(通过外部 animate-text 技能的 24 个 ID) | adapters/animate-text.md |
运行时选择
- GSAP 是 95% 动效工作的默认选择——涵盖时间线编排、变换、缓动、错开。本技能中的所有原子规则都基于 GSAP。
- Lottie 用于资源自带预烘托时间线的情况(通常是 After Effects 导出),包括会行走、做手势或反应的字符。
- Three.js 用于 3D 场景、摄像机运动、着色器驱动的视觉效果。
- Anime.js 用于轻量级补间动画,当使用 GSAP 显得大材小用时。
- CSS 用于简单的重复图案、装饰、闪光——无需 JavaScript 动画开销。
- WAAPI 用于无需 GSAP 依赖的原生浏览器关键帧动画。
- TypeGPU / WebGPU 用于 GPU 渲染的画布(粒子、液态玻璃、自定义着色器)。
多个运行时可以在一个合成中共存。每个运行时将其实例注册到特定于运行时的全局对象上,以便 HyperFrames 可以一次性在所有运行时中进行跳转。
关键约束
先决条件:hyperframes-core → 不可协商的规则(单条暂停时间线,data-duration 控制长度,不能使用 Math.random / Date.now / performance.now,不能使用 repeat: -1,不能对后期场景的片段进行页面加载时的 gsap.set,不能对 display 或原始 visibility 进行补间动画,以及在 async / setTimeout / Promise 内构建时间线)。核心规则允许在显式时间线边界上使用 GSAP 的 autoAlpha 和零持续时间可见性设置。仅在非片段元素或片段内的包装器上使用这些例外情况;框架拥有 .clip 的生命周期。不要在此处复述完整合约。
在核心合约基础上的动画创作附加项:
- 预计算的布局常量——永远不要在补间动画时通过
getBoundingClientRect()推导位置。补间动画时的 DOM 测量会因渲染器并行采样而不同步;在合成设置时计算一次坐标并在后续重复使用。 - 空间动效仅使用 GSAP 变换别名(
x,y,scale,rotation)。核心的白名单也允许对非空间属性使用opacity/color/backgroundColor/borderRadius进行补间动画——但永远不能使用width/height/top/left来修改布局。
脚本
node skills/hyperframes-animation/scripts/animation-map.mjs <composition-dir> \
--out <composition-dir>/.hyperframes/anim-map
读取注册在 window.__timelines 上的每个 GSAP 时间线,枚举补间动画,采样边界框,计算标志,输出 animation-map.json。在创作后使用它来审核编排(死区、错开一致性、生命周期警告)。
animation-map.mjs 首先尝试从当前项目解析辅助包,然后可以引导捆绑的 HyperFrames 包版本。仅在技能在捆绑的 CLI/技能安装之外运行,并且你需要显式固定该引导版本时,才设置 HYPERFRAMES_SKILL_PKG_VERSION=<version>。
参见
hyperframes-core——合成结构、数据属性、子合成、确定性渲染合约hyperframes-creative——调色板、字体排印、叙述、节拍规划(非动画创意指导)hyperframes-cli——npx hyperframes lint / check / snapshot / preview / render