企业官网建设流程全解析

HyperFrames whiteboard-ink 组件实战：让手绘白板草稿逐笔自绘

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

导读

whiteboard-ink是 HyperFrames 仓库registry/components/下的一个"手绘白板墨迹"视频原语（video primitive）：一段手绘 SVG 草图会像真实书写一样逐笔绘制出来，同时一支钢笔笔尖实时跟随当前墨迹前沿移动。它内置三套预设草图（bulb 灯泡、flow 流程图、rocket 火箭），并提供strokes插槽（slot）——把你自己编排的多笔 SVG 路径填入插槽，它们就会替代预设成为画面主体，笔尖跟随、逐笔节奏与墨迹法则（ink law）与预设完全一致。读完本文，你将掌握该组件的安装方式、五个变量（sketch/caption/pen/accent/exit）的完整语义、自定义笔画插槽的编写规则，以及如何把它挂载进宿主合成（composition）并理解其时间轴契约与确定性渲染原理。

组件概览与仓库文件

whiteboard-ink的完整实现位于 registry/components/whiteboard-ink/，共四个文件：

• whiteboard-ink.html：可挂载的子合成本体，也是安装目标（安装后写入compositions/components/whiteboard-ink.html）；
• registry-item.json：注册表元数据与变量块（variables block）声明；
• demo.html：用于 QA 的独立挂载示例；
• README.md：本文所依据的组件契约文档。

对应的官方目录页还生成了 docs/catalog/components/whiteboard-ink.mdx，提供可视化变量预览与安装命令。从registry-item.json的声明看，该组件type为hyperframes:component，family为intros-and-reveals，profile为ink-draw，打上了motion-primitive、svg、line-draw、slot等标签，并声明了一个同步点ink-complete（默认在 3.3s 处触发）。

五个核心变量：语义、默认值与取值表

组件变量定义在组件根节点data-composition-variables中（见 whiteboard-ink.html），并通过宿主元素上的data-variable-values传入。完整变量表如下：

从源码看，运行时通过window.__hyperframes.getVariables()读取这些值，并各自带有防御性回退：sketch非法时回退bulb、accent非法时回退green、exit非法时回退none（见 whiteboard-ink.html 中的变量解析段）。accent的三种颜色在脚本中以accentColors映射表实现，最终写入 CSS 变量--wbi-accent，供高亮笔画的描边引用；默认色值分别为var(--brand, #71f5a7)、var(--accent, #61a8ff)、var(--accent-2, #c5a3ff)。

值得注意的细节是：这些颜色用的是设计令牌（design token）引用而非硬编码颜色，因此组件外观会随宿主主题的令牌值变化，这也是其作为"原语"可复用的关键设计。

时间轴包络（Envelope）契约

组件的时间轴遵循"固定 IN 与 OUT、仅 HOLD 弹性"的包络模型：

• IN = 3.55s（其中 3.25s 为顺序绘制阶段，随后笔尖抬起并显示 caption）；
• OUT = 0.45s，仅当exit为fade或up时存在；
• HOLD 是唯一弹性阶段，用于吸收宿主挂载时长D与IN + OUT之间的差额：HOLD = max(0, D - IN - OUT)；
• 当D短于IN_BASE + OUT_BASE时，IN 与 OUT 会一起压缩（phaseScale = duration / fixedTotal）；
• 时间轴从不被整体缩放（time-scaled）——时长变化只会拉伸 HOLD 间隙，保证绘制节奏恒定；
• ink-complete同步点在默认参数下于 3.3s 触发（见 registry-item.json 的syncPoints声明）。

源码中的常量与此完全对应：DRAW_PHASE_BASE = 3.25、CAPTION_BASE = 0.3、IN_BASE = 3.55、OUT_BASE在exit=none时为 0、否则 0.45。绘制预算按"每笔最小时长 + 按长度加权分配剩余预算"切分，详见过渡段源码。

strokes 插槽：用你自己的 SVG 路径作画

这是whiteboard-ink最具扩展性的机制。组件的 SVG 内置了一个空命名组作为插槽：

<g class="wbi-sketch">npx hyperframes add whiteboard-ink

该命令会写入一个文件：compositions/components/whiteboard-ink.html（安装目标与 registry-item.json 中files[].target字段一致）。

第二步：在安装副本中填充插槽组

在compositions/components/whiteboard-ink.html中，向插槽组填入你自己的路径。下面是一个自绘"信号"（signal）标记、并带一条强调下划线的示例：

<g class="wbi-sketch"><div class="clip" contenteditable="false">【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes