一个组件是一段能复用的动效:弹簧驱动的形状、翻页、纸面转场、章节进度条、一块块搭起来的建筑,以及给太干净的画面收尾的一遍(film-finish)。它分两层:
- 状态层:
state(params, t)算出这一帧的样子(位置、大小、透明度、进度、切片),是 t 的纯函数,不碰 DOM 和画布; - 落笔层:薄薄一层,把状态画出来。
canvas(ctx, state, …)画进 2D canvas;dom(…)改 DOM 元素的样式和文字;three(mesh, state, params, THREE)改 Three.js 对象(比如InstancedMesh每个实例的矩阵),three 由调用的人传进来,组件自己不引入它。字幕、章节条、标题卡这类以字为主的组件 canvas 和 DOM 两种都有,在 HyperFrames 里用 DOM 排,中文断行、字距、字体特性都交给浏览器;颗粒、纸纹、翻页这类效果只有 canvas 一种;3D 的(build-up)有 canvas(2.5D 方块,样片和不用 3D 的片子用)和 three 两种。
同一份状态,HyperFrames 的合成、canvas-film 的页面、风格样片的场景都能用;硬规则 1 由状态层保证:同一个 t 永远算出同一个状态,乱序画也一样。
bin/vh components list 列出全部组件、各自有哪几种落笔、一句话说明(--json 给机读的参数表)。参数表在每个组件的 slots.json:
{"version": 1, "name": "chapter-bar", "summary": "…", "painters": ["canvas", "dom"],
"slots": [{"name": "chapters", "type": "array", "default": [], "text": "…"}, …], "provenance": [...]}每个参数有类型、默认值、取值范围和一句话;component.js 导出的 defaults 和它对得上(bin/vh components check 查)。
组件共用的计算和画法,也是风格样片的 lib(styles/_swatch/lib.js 把它整个转出去,再加上样片自己的内容规格):
| 文件 | 有什么 |
|---|---|
core.js |
画面(FRAME、setFrame)、时间(frame、step、seg、env、tween)、安全框(safeBoxes、anchor、slots)、数学、带种子的哈希和噪声、缓动、闭式弹簧(spring、springTrack)、颜色和 tokens |
motion.js |
改目标不留状态的弹簧轨道(track、colorTrack、hold)、内容换位(swap)、光标的路线和按压(cursorPath、presses)、声明式场景的状态(scene) |
text.js |
从风格 tokens 取字体,canvas 里逐字排版和画字,解码和打字机 |
paint.js |
离屏图层、质感(颗粒、纸、网点、扫描线、暗角、墨晕、毛边、RGB 分离)、手绘线、通用转场(擦除、光圈、甩镜、运动模糊) |
gl.js |
离屏 WebGL2 全屏着色器 |
画面的尺寸和帧率是一个设置:默认 1920×1080、30 fps、dpr 1(样片的),别的页面在第一帧之前调一次 setFrame({ w, h, fps, dpr })。出 4K(dpr 2)时,canvas 按 w·dpr 开、ctx.scale(dpr, dpr),坐标照旧按 CSS px 写(engines/README.md"出 4K");不给尺寸的图层跟着 dpr 开,库里把图层画回去的地方都按 CSS 尺寸画。
组件和库都是 ES 模块,用到哪个就复制进项目(projects/ 以外的东西不改,CLAUDE.md 硬规则 6):
bin/vh components add <项目> chapter-bar page-turn # 复制 lib/ 和这两个组件到 <项目>/components/,打印怎么接- HyperFrames:合成里
<script type="module">引入组件,在挂在时间线上的驱动 tween 里按 t 调state()和落笔(engines/README.md"最小写法"的驱动 tween)。字用 DOM 落笔。 - canvas-film:
film.html加一行<script type="module" src="components/lib/global.js"></script>,经典脚本里用OVH.grain(X, t, {…})这样调(模块在ready之前就加载完了);画尺寸不是 1920×1080 的,在ready里OVH.setFrame({ w: W, h: H, fps: FILM.fps, dpr: PRX })。有 three 画法的组件配 Three.js 层用:在FILM.three.build里await import(new URL("components/<名字>/component.js", document.baseURI).href),在镜头的pose(t)里调它的three()(build-up/sample/three-film.js是一支完整的例子)。 - 风格样片和配方草图:场景从
../../components/<组件>/component.js引入(样片的 stage 会把components/一起复制过去,同vendor/的约定)。
每个组件带一段 5 秒的样片:<组件>/sample/ 是一个样片场景(swatch.js + tokens.json,接口同 styles/_swatch/README.md),bin/vh components sample <组件> 用样片渲染器渲出来(sample/media/swatch.mp4 不入库),联系表存成 sample/media/sheet.jpg 入库:agent 读这张图,就知道这个组件动起来是什么样子。
build-up 的联系表是它的 canvas 落笔画的(2.5D 方块),不是 three 落笔,也没有 HDRI;three 落笔的样子看 build-up/sample/three-film.js 渲出的帧。canvas 落笔按每块中心由远到近排着画,只对一样大的盒子排得对,大小不一的盒子前后会排错,要准确的遮挡就用 three 落笔。
- 新建
components/<名字>/:component.js导出defaults、state(params, t)和至少一种落笔;slots.json写参数表;sample/放一个 5 秒的样片场景。 - 状态层只用
lib/和参数,不读Math.random、Date.now、DOM,不留跨帧状态;要缓存,就缓存只由参数决定的东西。 - 借来的代码:MIT、Apache-2.0 这类许可的,把许可原文放进
LICENSES/,在NOTICE.md加一行,文件头写明出处;只借思路的,文件头写一句跟的是谁的思路。 bin/vh components check,再bin/vh components sample <名字>,看联系表。