企业官网建设流程全解析

HyperFrames CSS 动画适配器实战指南：让 CSS Keyframes 在预览与渲染中实现确定性 Seek

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

HyperFrames 通过内置的css运行时适配器（adapter）支持对 CSS Keyframes 动画进行确定性寻帧（seek），使纯 CSS 编写的动画在 Studio 预览、时间线拖拽和最终渲染中始终保持同一帧画面。本指南以 css-animations.md 为核心，结合 css.ts 适配器源码与 init.ts 时长推断逻辑，讲解 CSS 动画的适用范围、编写契约、两种高频模式（单元素动画与交错动画）、时长自动推断机制，以及npx hyperframes lint对缺失时长来源的校验规则。读完你能够独立编写可在 HyperFrames 中可预测渲染的纯 CSS 动效元素，并理解其底层 seek 原理。

适用范围：什么场景该用 CSS 动画，什么场景该用 GSAP

CSS 动画在 HyperFrames 中的定位非常明确：适合单一元素上、时长固定的简单重复动效，例如：

• 装饰性循环动画（已知重复次数的脉冲、呼吸、旋转）；
• 遮罩（mask）、辉光（glow）、微光（shimmer）、颗粒（grain）、轻微视差层等背景氛围层；
• 单个元素的入场动效——当为它单独写一个完整 JS 时间线显得过重时。

而涉及多元素时间线编排的场景编排（scene choreography），原文档明确建议改用 GSAP：GSAP 时间线自带总时长信息，window.__timelines中的时间线对象会被渲染引擎直接识别，无需额外声明。CSS 动画没有时间线对象，其总时长依赖运行时的推断逻辑（见下文「时长推断」），因此它更适合"动效只属于某一个元素、且有固定时长"的装饰性用途。

适配器契约：让 CSS 动画可被确定性寻帧的前提

css适配器在初始化后通过discover()扫描全文档、找出所有计算样式（computed style）中animation-name非none的元素，并记录其原始animation-delay与animation-play-state内联样式用于后续恢复（见 css.ts）。为了让这一发现与寻帧过程可靠工作，编写 CSS 动画时需要遵守以下契约：

1. 在运行时初始化完成之前把动画元素放入 DOM。适配器只在discover阶段扫描一次元素，初始化后动态插入的动画元素不会被识别，也就无法被 seek。
2. 给有时序的元素设置data-start，使元素的本地动画时间与剪辑（clip）时间对齐。seek 时本地时间按Math.max(0, time - start)计算（css.ts），即元素在剪辑开始后data-start秒才"启动"。
3. 使用有限（finite）的animation-duration与animation-iteration-count。因为在不支持 WAAPI-backed CSS 动画的环境中，适配器会退化为"暂停 + 负animation-delay"方案，该方案无法表达无界时长。
4. 优先使用animation-fill-mode: both，使 seek 到的状态在动效开始前和结束后都能保持（both= 向前填充from帧 + 向后填充to帧）。
5. 避免依赖墙钟 JavaScript、hover 触发的状态、以及依赖用户事件的 class 切换。渲染引擎是在无用户交互的浏览器环境中逐帧捕获的，这些机制会造成预览帧与渲染帧不一致。

基本模式：单元素脉冲环（pulse-ring）

最典型的使用方式是给一个元素配上data-start、data-duration、data-track-index属性，并在<style>中定义有限次数的 keyframes。以下为原文档的完整示例：

<div id="pulse-ring" class="clip pulse-ring" ><div class="clip dots"><div >npx hyperframes lint npx hyperframes check

lint负责静态校验（包括上述root_composition_missing_duration_source规则），check负责运行时层面的合成检查。二者配合可在渲染前把「时长缺失」「动画不可寻帧」类问题拦截在编辑阶段。

参考与延伸阅读

• 适配器源码：packages/core/src/runtime/adapters/css.ts
• 时长自动推断：packages/core/src/runtime/init.ts 中的resolveAdapterDurationFloorSeconds与getSafeTimelineDurationSeconds
• 适配器接口契约（含getInferredDurationSeconds语义说明）：packages/core/src/runtime/types.ts
• 适配器单元测试（seek 回退、WAAPI 路径、时长推断边界）：packages/core/src/runtime/adapters/css.test.ts
• lint 时长来源规则：packages/lint/src/rules/composition.ts 及对应测试 composition.test.ts

【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes