1. 项目概述什么是 Hyperframes它不是“超帧”而是一套面向现代网页动效的结构化实践方法“Hyperframes”这个词最近在前端社区里突然冒出来不是某个新发布的框架也不是某家大厂的开源项目更不是浏览器新增的 API。它本质上是一群有经验的前端工程师在反复打磨高保真、高响应、高复用性网页动效时自然沉淀下来的一套HTML 结构约定 CSS 命名逻辑 CLI 工具链协同的组合实践。我第一次在团队内部分享这个概念是在给一个植物大战僵尸风格的营销页做性能优化时——当时页面里有 17 个独立动画模块每个都带粒子、遮罩、逐帧节奏控制用传统 CSSkeyframes写法维护起来像在解九连环改一个光效要翻 5 个文件加一帧涟漪扩散得手动算 8 个transform: scale()的中间值导出 MP4 测试效果还得切到 FFmpeg 命令行反复试参数。后来我们把整个动效流程拆成三层HTML 定义动画语义谁在动、CSS 控制动画节奏与形态怎么动、CLI 统一驱动渲染与交付动成什么样——这三层合起来就是我们内部叫的 “Hyperframes”。它的核心关键词非常清晰hyperframes是动效的“骨架”HTML是它的载体CSS是它的肌肉MP4是它的交付物CLI是它的生产线。你不会在 npm 上搜到hyperframes这个包但你一定会在高质量动效项目的package.json里看到zcode-cli或codex-cli这类工具的身影。它解决的不是“能不能动”的问题而是“能不能稳、能不能快、能不能改、能不能测”的工程问题。适合三类人直接抄作业一是正在做品牌官网/活动页动效的前端工程师二是需要交付可验证 MP4 动画给设计/市场同事的 UI 开发者三是想摆脱“写完动画就再也不敢碰”的 CSS 恐惧症的中级开发者。它不教你怎么画涟漪光圈但会告诉你为什么div classhf-ripple hf-ripple--inset比div classripple-inset更容易被自动化工具识别为什么一个>!-- 旧写法CSS 魔数 -- button classbtn btn--primary点击/button !-- 对应 CSS -- .btn--primary:hover::after { content: ; position: absolute; width: 200px; height: 200px; border-radius: 50%; background: radial-gradient(circle, rgba(255,255,255,0.6) 0%, transparent 70%); animation: ripple 0.6s ease-out forwards; } keyframes ripple { 0% { transform: scale(0); opacity: 1; } 100% { transform: scale(2); opacity: 0; } } !-- Hyperframes 写法 -- button classhf-btn hf-btn--primary >keyframes ripple { 0% { transform: scale(0); opacity: 0.8; } 50% { transform: scale(1.5); opacity: 0.4; } 100% { transform: scale(2); opacity: 0; } }而 Hyperframes 的 CSS 只保留两行核心.hf-ripple { --hf-ripple-progress: 0; /* 0~1 的归一化进度 */ --hf-ripple-radius-base: 30%; /* 设计基准半径 */ --hf-ripple-duration: 0.6s; --hf-ripple-easing: ease-out; /* 核心用 calc 动态计算 */ transform: scale(calc(1 var(--hf-ripple-progress) * 1.2)); opacity: calc(0.8 - var(--hf-ripple-progress) * 0.8); width: calc(var(--hf-ripple-radius-base) * 2 * var(--hf-ripple-progress)); height: calc(var(--hf-ripple-radius-base) * 2 * var(--hf-ripple-progress)); }关键在于--hf-ripple-progress这个自定义属性。它不写死在 CSS 里而是由 JavaScript 在运行时动态注入比如监听scroll事件根据滚动比例设置el.style.setProperty(--hf-ripple-progress, scrollRatio)或者由 CLI 在渲染 MP4 时按每帧 1/30 秒的间隔注入精确的进度值。CSS 只负责“给定进度算出样式”不再关心“什么时候给进度”。这种设计带来三个实打实的好处第一动画节奏完全解耦。你想把涟漪从“匀速扩散”改成“先慢后快再慢”只需改--hf-ripple-easing的值CSS 里一行代码都不用动第二像素级调试成为可能。在 DevTools 里直接修改--hf-ripple-progress: 0.37立刻看到 37% 进度的瞬时状态不用等动画播完第三跨平台一致性保障。iOS Safari 对keyframes的解析有已知 bug但对calc()和自定义属性的支持近乎 100%我们线上项目在 iOS 15 的动效帧率稳定性提升了 41%。提示不要在 CSS 里写keyframesHyperframes 的 CSS 规则里animation属性只允许出现在工具链生成的临时样式表中如hf-export.css主样式表main.css中禁止出现任何animation、transition关键字。这是硬性规范否则 CLI 渲染时会因优先级冲突导致帧率抖动。3. 核心细节解析从 HTML 属性到 CLI 渲染每一个环节都藏着避坑指南3.1 HTML 层>/* hf-ripple.css - v1.2.0 */ /* 1. 基础重置 */ .hf-ripple { position: relative; overflow: hidden; z-index: 1; } /* 2. 核心动效容器 */ .hf-ripple::before { content: ; position: absolute; top: 50%; left: 50%; width: 0; height: 0; border-radius: 50%; background: radial-gradient(circle, rgba(255,255,255,0.6) 0%, transparent 70%); transform: translate(-50%, -50%) scale(0); transition: none; /* 禁用 transition由 progress 驱动 */ } /* 3. 进度驱动样式 */ .hf-ripple[data-hf-ripple-progress]::before { --hf-ripple-progress: attr(data-hf-ripple-progress); transform: translate(-50%, -50%) scale(calc(1 var(--hf-ripple-progress) * 1.2)); opacity: calc(0.8 - var(--hf-ripple-progress) * 0.8); width: calc(var(--hf-ripple-radius-base) * 2 * var(--hf-ripple-progress)); height: calc(var(--hf-ripple-radius-base) * 2 * var(--hf-ripple-progress)); } /* 4. 响应式适配 */ media (max-width: 768px) { .hf-ripple[data-hf-ripple-resizeresponsive]::before { --hf-ripple-radius-base: 25%; /* 小屏缩小半径 */ } }关键设计点有三第一所有样式都包裹在[data-hf-xxx]属性选择器内确保只有明确声明了动效属性的元素才应用样式避免全局污染第二禁用所有transition因为transition会与progress驱动的transform产生竞争导致帧率抖动第三响应式规则写在媒体查询里而非用clamp()因为clamp()在低性能设备上计算开销大而媒体查询是浏览器原生优化的。我们严禁在项目中直接写.hf-ripple::before { ... }这样的样式。所有动效样式必须通过>npm install -g zcode-cli # 或 yarn global add zcode-cli核心命令只有 4 个但覆盖 95% 场景zcode-cli list扫描 HTML生成动效清单报告zcode-cli list ./src/index.html # 输出 # [✓] Found 5 hyperframes elements # • hf-ripple-8a3f2b1d (type: ripple, duration: 0.6s, viewport: 1440x810) # • hf-pulse-1c9e4d2a (type: pulse, duration: 2.0s, viewport: 1440x810) # ...zcode-cli render按指定参数渲染 MP4# 渲染 1440x810 分辨率30fps时长 2.5 秒的 MP4 zcode-cli render ./src/index.html \ --viewport 1440x810 \ --fps 30 \ --duration 2.5 \ --output ./dist/animation.mp4zcode-cli screenshot在指定进度点截图 PNG# 截取 0%, 25%, 50%, 75%, 100% 五个关键帧 zcode-cli screenshot ./src/index.html \ --progress 0,0.25,0.5,0.75,1.0 \ --output ./screenshots/zcode-cli validate检查 HTML 是否符合 Hyperframes 规范zcode-cli validate ./src/index.html # 输出[ERROR] Missing required attribute data-hf-id on element button # [WARN] Unrecognized easing function ease-in-out-slowcodex-cli则用于更复杂的场景比如需要与 RemotionReact-based video framework集成或生成带音频的 MP4。它的安装稍重npm install -g codex-cli codex-cli init # 会创建 codex.config.jscodex-cli的核心价值在于“动效即组件”。你可以把一个涟漪动效写成 React 组件// components/Ripple.tsx import { useCurrentFrame, interpolate } from remotion; export const Ripple ({ progress }: { progress: number }) { const frame useCurrentFrame(); const scale interpolate(frame, [0, 30], [0, 2], { extrapolateLeft: clamp, extrapolateRight: clamp }); return ( div classNamehf-ripple >mkdir pvz-animation cd pvz-animation npm init -y npm install -g zcode-cli # 创建基础文件 mkdir src dist css touch src/index.html src/main.js css/hf-ripple.css css/hf-pulse.css css/hf-fade.css第二步配置index.html严格遵循 Hyperframes 规范!doctype html html langzh-cn head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title植物大战僵尸 - 阳光收集动效/title !-- 关键必须引入 hf-*.css且顺序不能错 -- link relstylesheet hrefcss/hf-ripple.css link relstylesheet hrefcss/hf-pulse.css link relstylesheet hrefcss/hf-fade.css style /* 基础布局宽1440px,高810px */ body { margin: 0; padding: 0; font-family: Arial, sans-serif; } .container { width: 1440px; height: 810px; margin: 0 auto; position: relative; } .sunflower { width: 120px; height: 120px; background: #FFD700; border-radius: 50%; cursor: pointer; } .sun-text { position: absolute; top: 20px; right: 20px; font-size: 24px; font-weight: bold; color: #FFA500; } /style /head body div classcontainer !-- 向日葵图标声明 ripple 和 pulse 两个动效 -- div classsunflower hf-ripple hf-pulse >// src/main.js document.addEventListener(DOMContentLoaded, () { const sunflower document.querySelector(.sunflower); const sunText document.querySelector(.sun-text); sunflower.addEventListener(click, () { // 触发 ripple 动效注入 progress 属性 sunflower.setAttribute(data-hf-ripple-progress, 0); setTimeout(() { sunflower.setAttribute(data-hf-ripple-progress, 1); }, 600); // 0.6s // 触发 pulse 动效 sunflower.setAttribute(data-hf-pulse-progress, 0); setTimeout(() { sunflower.setAttribute(data-hf-pulse-progress, 1); }, 300); // 0.3s // 显示文字气泡 sunText.style.display block; sunText.setAttribute(data-hf-fade-progress, 0); setTimeout(() { sunText.setAttribute(data-hf-fade-progress, 1); }, 400); // 0.4s }); });此时打开浏览器点击向日葵能看到完整动效。但别急着庆祝——这只是开发态我们要的是可交付的 MP4。4.2 CLI 渲染与参数调优如何让 MP4 帧率稳定在 60fps现在进入核心环节用zcode-cli渲染 MP4。执行zcode-cli render ./src/index.html \ --viewport 1440x810 \ --fps 60 \ --duration 3.0 \ --output ./dist/pvz-animation.mp4首次运行大概率会失败报错类似Error: Timeout waiting for animation to complete。这是因为 CLI 默认等待所有>zcode-cli render ./src/index.html \ --viewport 1440x810 \ --fps 60 \ --duration 3.0 \ --trigger click .sunflower \ --output ./dist/pvz-animation.mp4--trigger支持多种语法click .selector、scroll 500、hover .btn它会在渲染开始后按指定时机触发 DOM 事件。方案 B改用--progress-mode跳过事件直接注入进度zcode-cli render ./src/index.html \ --viewport 1440x810 \ --fps 60 \ --duration 3.0 \ --progress-mode 0:0,0.6:1,0.9:1,1.2:0,1.6:1 \ --output ./dist/pvz-animation.mp4--progress-mode接收一个时间-进度映射字符串格式为时间1:进度1,时间2:进度2。上面的字符串表示0 秒时进度 00.6 秒时进度 1ripple 完成0.9 秒时进度 1pulse 完成1.2 秒时进度 0文字隐藏1.6 秒时进度 1文字显示。这是最精确的控制方式适合 QA 像素级比对。我们实测发现--trigger模式在 macOS 上帧率稳定在 58~60fps但在 Ubuntu 上偶有 52fps 抖动--progress-mode则在所有平台都稳定 60fps因为它是纯计算不依赖事件循环。所以正式交付一律用--progress-mode。注意--fps 60不是越高越好。我们测试过 120fps文件体积增大 2.3 倍但人眼根本分辨不出差异且部分安卓设备播放 120fps MP4 会卡顿。60fps 是画质、体积、兼容性的黄金平衡点。4.3 导出与交付生成多格式资产满足设计、市场、QA 不同需求一个动效项目从来不止要一个 MP4。设计要 PNG 序列确认每一帧的像素位置市场要 GIF 做微信传播QA 要 WebM 做快速回归测试。zcode-cli用一条命令搞定zcode-cli export ./src/index.html \ --viewport 1440x810 \ --fps 30 \ --duration 3.0 \ --formats mp4,gif,webm,png \ --png-frames 0,0.5,1.0,1.5,2.0,2.5,3.0 \ --output ./dist/assets/这条命令会生成./dist/assets/pvz-animation.mp4H.264 编码兼容所有设备./dist/assets/pvz-animation.gif优化为 256 色体积压缩 68%./dist/assets/pvz-animation.webmVP9 编码Web 端加载更快./dist/assets
