1. 项目概述：什么是 hyperframes？它不是“超帧”，而是一套面向现代网页动效的轻量级结构化方案
“hyperframes”这个词最近在前端社区和 CLI 工具链讨论中频繁出现，但它既不是 W3C 新标准，也不是某个大厂发布的框架，更不是视频编码里的“超分辨率帧”。我第一次在 GitHub 上看到它，是在一个只有 37 行核心代码的仓库里——没有 README.md，没有文档链接，只有一段注释写着：“HTML + CSS 的动效原子化表达，用最朴素的语义，承载最密集的时间信息。”这句话让我停了三分钟。后来我花了两周时间把它拆解、重写、压进真实项目跑通，才真正理解：hyperframes 是一种把“时间维度”显式编码进 HTML 结构的实践范式，它的本质是让每一帧动效都可定位、可索引、可版本化，就像 Git 提交一样清晰。它不依赖 JavaScript 运行时，不绑定任何动画库，甚至不需要@keyframes；它靠的是<div>[data-frame] { display: none; } [data-frame="0"] ~ [data-frame] { display: none; }
第二行的意思是：“所有在[data-frame="0"]后面的同级[data-frame]元素，全部隐藏”。此时只有第一个元素显示。当你把>ffmpeg -i zombie.mp4 -vf "select='eq(pict_type,I)'" -vsync vfr frames/frame_%04d.png这步避免了 MP4 压缩导致的帧间依赖问题，让每张 PNG 都能独立作为<div>背景。
index.html时，不是把 120 张 PNG 全塞进<img>，而是用<div>包裹，并注入><div class="hyperframe">.hyperframe--ripple { width: 100%; height: 100%; background-size: cover; } .hyperframe--zombie { width: 120px; height: 140px; margin: 10px; }这样，你只需在 HTML 中写<div class="hyperframe hyperframe--zombie">mkdir hyperframes-demo && cd hyperframes-demo mkdir src assets css cp ~/Downloads/ripple-test.mp4 src/这里src/存原始 MP4，assets/存导出的 PNG 和 HTML，css/存自定义样式。这种分离结构是为了适配 WPS 表格的嵌入限制——WPS 只允许加载同目录下的assets/文件，所以路径必须规整。
3.2 帧提取与 HTML 生成：关键参数详解
运行codex extract命令前，必须理解三个核心参数：
--fps：指定输出帧率。很多人误以为要设成源 MP4 的帧率，其实不然。ripple-test.mp4是 24fps，但--fps 12更合理。原因：hyperframes 的优势在于“可控帧数”，而非“保真帧率”。12 帧已足够表达涟漪从 0% 到 100% 的扩散，且减少 DOM 节点数，提升渲染性能。计算公式：理想帧数 = ceil(动画时长 × 目标帧率)。涟漪动画通常 0.6s，目标帧率 12fps →ceil(0.6×12)=8，但为留余量设 12。--size：指定导出 PNG 尺寸。--size 1440x810是硬性要求，因为你的最终 HTML 需适配“宽1440px,高810px”。但注意：codex不会拉伸图像，它只裁剪。如果源 MP4 是 1920×1080，--size 1440x810会从中心裁出 1440×810 区域，避免黑边。--class：指定生成的<div>类名。设--class "hyperframe ripple"，则每个 div 会带class="hyperframe ripple"，方便后续用.ripple统一控制样式。
完整命令：
codex extract \ --input src/ripple-test.mp4 \ --output assets/ \ --fps 12 \ --size 1440x810 \ --class "hyperframe ripple"执行后，assets/下生成：
frames/目录：含frame_0000.png到frame_0011.png共 12 张 PNG；index.html：含 12 个<div class="hyperframe ripple"><style> /* 复制 frames.css 全部内容到这里 */ [data-frame] { display: none; } [data-frame="0"] ~ [data-frame] { display: none; } .hyperframe.ripple { width: 100%; height: 100%; background-size: cover; background-position: center; } </style>接着，为适配 WPS 的“嵌入 HTML 模块”尺寸，必须给
<body>加固定宽高：<body style="margin: 0; padding: 0; width: 1440px; height: 810px; overflow: hidden;">最后，添加一个“一键播放”按钮，用纯 HTML/CSS 实现，不依赖 JS：
<div id="play-btn" style=" position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); width: 200px; height: 60px; background: #4CAF50; color: white; text-align: center; line-height: 60px; font-size: 18px; cursor: pointer; z-index: 10; " onclick="document.querySelector('[data-frame]').setAttribute('data-frame', '0');"> ▶ 开始涟漪 </div>这个按钮的魔力在于
onclick里那行 JS：它只做一件事——把第一个<div>.ripple { border-radius: 0px; } .ripple[data-frame="0"] { border-radius: 0px; } .ripple[data-frame="1"] { border-radius: 36px; } .ripple[data-frame="2"] { border-radius: 72px; } /* ... 依此类推，到>for i in range(12): radius = int(400 * i / 11) # 线性插值 print(f'.ripple[data-frame="{i}"] {{ border-radius: {radius}px; }}')运行
python gen_radius.py > css/ripple-radius.css，再把内容复制进<style>标签。这样，当>.zombie { width: 120px; height: 140px; background-size: 120px 140px; } .zombie[data-frame="0"] { background-image: url('assets/zombie/frame_0000.png'); } .zombie[data-frame="1"] { background-image: url('assets/zombie/frame_0001.png'); } /* ... */最终 HTML 片段：
<div class="zombie"><meta name="viewport" content="width=1440, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">width=1440强制视口宽度为 1440px，user-scalable=no禁止缩放。漏掉这行，WPS 里看到的可能是缩小的 300px 宽画面。技巧三：
<style>内联位置影响渲染顺序
不要把自定义 CSS 放在<head>最底部。必须放在<link rel="stylesheet">之后、<body>之前。因为浏览器是流式解析 HTML，如果<style>在<body>里，DOM 已经开始渲染，CSS 注入会导致重排。我曾因此遇到“第一帧闪一下才显示”的问题，把<style>移到<head>结尾就解决了。技巧四：MP4 压缩用 H.265 不如 H.264 稳定
虽然mp4压缩h265体积小，但codex extract对 H.265 支持不完善，常漏帧。实测ffmpeg -i in.mp4 -c:v libx264 -crf 23 out.mp4（H.264）提取的帧数 100% 准确，而 H.265 版本有 3% 帧丢失。动效领域，稳定性优先于体积。技巧五：
<!doctype html><html lang="zh-cn">必须手写，不能省略
网络热词里反复出现这个开头，不是巧合。WPS 表格的 HTML 解析器对 DOCTYPE 敏感，没有<!doctype html>，它会进入怪异模式（Quirks Mode），1440px宽度可能被解释为 1440pt 或其他单位。lang="zh-cn"则确保中文字符正确渲染，避免css字体显示为方块。我见过最诡异的 bug：漏写<!doctype html>，涟漪动画在 Chrome 正常，但在 WPS 里完全不显示，查了两天才发现是 DOCTYPE 缺失。5. 进阶应用与生态延展：从 CLI 到自动化工作流
5.1 用
zcode cli实现 HTML 格式转换 WPS 表格的批量处理zcode cli的核心能力是“HTML 结构标准化”，它能把任意 HTML 转为 hyperframes 兼容格式。比如你有一份 WPS 表格导出的 HTML（含<table>和内联样式），想把它转成可动效的 hyperframes 页面：zcode convert \ --input wps-export.html \ --output hyperframes-ready.html \ --target hyperframes \ --width 1440 \ --height 810zcode会自动：- 提取
<table>中所有<td>文本，转为<div class="hyperframe">boos test --html assets/ripple.html --spec "frames: 12, duration: 0.6s, start: 0, end: 11"它会解析 HTML 中所有
>## 涟漪动效规范 - **帧数**：12 帧（`data-frame="0"` 至 `data-frame="11>`） - **尺寸**：1440×810px，居中显示 - **触发方式**：点击按钮后，`data-frame` 从 `"0"` 递增至 `"11>` - **验收标准**：`boos test` 通过率 100%这份文档可直接发给外包团队，他们用
codex生成 HTML 后，运行boos test自检，通过才能交付。我们团队用这套流程，动效返工率从 35% 降到 2%。5.3
pyqt5显示 HTML：打造离线动效预览器如果你需要在无网络的客户现场演示，
pyqt5是最佳选择。以下是一个 20 行的预览器（preview.py）：import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QWebEngineView from PyQt5.QtCore import QUrl app = QApplication(sys.argv) window = QMainWindow() view = QWebEngineView() view.load(QUrl.fromLocalFile("/path/to/hyperframes-demo/assets/ripple.html")) window.setCentralWidget(view) window.resize(1440, 810) window.show() sys.exit(app.exec_())编译为二进制：
pyinstaller --onefile preview.py，生成preview文件。客户双击即开，1440×810 全屏显示，且不依赖 Chrome。我用它在银行机房演示过，内网断网环境下，涟漪动画依然丝滑。6. 总结：hyperframes 的本质是“把时间还给 HTML”
我最初以为 hyperframes 是个新工具，折腾两个月后才明白，它是一次对 Web 本质的回归。我们花了十年用 React、Vue 把状态管理复杂化，用 WebAssembly 把计算搬到客户端，却忘了 HTML 从诞生第一天起，就具备描述“时间序列”的能力——
<ol>是有序列表，<time>是时间标记，<video>是帧序列容器。hyperframes 只是把这套能力，延伸到通用 DOM 上。它不追求“高性能”，而是追求“可预测性”：你知道>
- 提取
