企业官网建设流程全解析

HyperFrames 实战：以 shimmer-sweep 为例掌握 Registry 组件的安装、接线与定制

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

本篇以「给标题文字添加一道流动高光（shimmer light sweep）」为完整示例，演示 HyperFrames 中组件（component）从hyperframes add安装、读取片段、接线进宿主合成（composition）、lint/preview校验，到通过 CSS 变量与 GSAP 时间线参数定制的全流程。读完后你将掌握组件与块（block）的本质区别、hyperframes add的完整参数语义，以及把任意注册表组件安全合并进自己合成的标准套路。

1. 先厘清概念：组件（Component）与块（Block）的区别

HyperFrames 的注册表（registry）提供两类可复用单元，hyperframes-registry SKILL 中的定义是：

• 块（Block）——独立的子合成（sub-composition），拥有自己的画布尺寸、时长和时间线，通过宿主合成中的data-composition-src引用挂载；
• 组件（Component）——效果片段（effect snippet），没有独立的尺寸与时间线，直接粘贴进宿主合成的 HTML，并跟随宿主合成的时间线一起运动。

本文的 shimmer-sweep 属于后者。这一点决定了后续接线方式：你不需要像接线块那样填data-composition-src、data-start等挂载属性，而是把片段里的 HTML、CSS、JS 三部分分别合并到自己的合成文件中。组件的长度、时长继承自宿主合成，因此接线时无需关心画布尺寸，只需把组件元素摆放在正确的 z-index 层级上（见 组件接线参考）。

2. 场景设定

用户已有一个 HyperFrames 项目，希望给标题文字加一道流光扫过的高光（shimmer light sweep），让标题看起来更有质感。这是一个典型的组件接入场景：效果本身没有独立时间线，只是叠加在已有标题之上的一段高光动画。

3. 第 1 步：安装组件

hyperframes add shimmer-sweep

该命令在 add 命令实现 中的定义是"从注册表安装一个块或组件到当前项目"。实际安装流程由runAdd完成（见 packages/cli/src/commands/add.ts），关键行为包括：

• 按名字解析：name参数先按精确条目名解析；若没有同名条目且该值恰好是标签（tag），则批量安装该标签下的所有块（hyperframes add captions会装下所有captions标签的块）；
• 依赖先行：解析结果按拓扑排序，registryDependencies先安装，请求的条目最后安装；
• 自动创建配置：若项目还没有hyperframes.json但存在index.html，命令会用默认配置自动生成；
• 示例除外：add只处理块和组件，若名字解析出的是示例（example），会明确报错并提示改用hyperframes init <dir> --example <name>。

安装成功后，CLI 会打印写入的文件列表，以及一条接线片段（include snippet）。对组件来说，打印的片段是<!-- paste from compositions/components/shimmer-sweep.html into your composition -->形式的注释提示，因为组件没有挂载属性，真正的"接线"就是手工合并文件内容（块才会打印data-composition-src挂载 div，见 buildSnippet）。

add命令还支持以下常用参数（源码中的参数定义见 packages/cli/src/commands/add.ts）：

另外值得注意的工程细节：条目文件每次安装都会重新拉取，不做本地缓存（只有 manifest 会缓存 24 小时）。因此离线时你可以搜索、可以查看条目信息，但安装必然失败——describeInstallFailure会把网络类错误明确提示为"注册表主机或网络问题，而非命令本身写错"（见 packages/cli/src/commands/add.ts）。

4. 第 2 步：阅读已安装的片段文件

安装完成后，打开compositions/components/shimmer-sweep.html，先读文件顶部的注释头（comment header）。这是所有注册表片段的约定：注释头说明用法、可定制的 CSS 变量及其默认值。这一步不能跳过——不同组件暴露的定制点不同，注释头就是它的"使用说明书"。

默认情况下，组件安装到compositions/components/<name>.html。这个路径不是写死的，而是由项目根目录的hyperframes.json配置：

{ "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json", "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry", "paths": { "blocks": "compositions", "components": "compositions/components", "assets": "assets" } }

paths.components控制组件安装目录，paths.blocks控制块安装目录。底层实现中，remapTarget会读取该配置，把条目清单里以compositions/或compositions/components/开头的目标路径前缀重映射为用户配置的目录（见 packages/cli/src/commands/add.ts）。例如把paths.blocks改成"scenes"后，hyperframes add><div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)"> <h1 class="title">AI-Powered Video</h1> </div>

这段标记要放在你合成的<div>document.querySelectorAll(".shimmer-sweep-target").forEach((el) => { if (!el.querySelector(".shimmer-mask")) { const mask = document.createElement("div"); mask.className = "shimmer-mask"; el.appendChild(mask); } });

这段脚本是幂等的：已存在.shimmer-mask的容器不会被重复添加，因此多个组件共享同一段脚本或重复执行也不会产生脏 DOM。

5.4 Timeline——把扫动动画挂进时间线

shimmer-sweep 组件暴露了 GSAP 时间线集成接口（是否暴露、如何暴露，在片段注释头中说明）。把下面的调用加入你的 GSAP 时间线，让高光从-20%扫到120%：

tl.fromTo( ".shimmer-sweep-target", { "--shimmer-pos": "-20%", }, { "--shimmer-pos": "120%", duration: 1.2, ease: "power2.inOut", stagger: 0.15, }, 1.5, );

这里动画的不是普通 CSS 属性，而是自定义属性--shimmer-pos（高光位置百分比），stagger: 0.15让多个目标元素依次起扫形成波浪感，1.5是时间线插入位置（秒）。这正是组件的核心价值：它复用宿主合成已有的 GSAP 时间线，而不是另起一套动画时钟。

6. 第 4 步：Lint 与预览

hyperframes lint hyperframes preview

hyperframes lint在接线后校验结构问题（未包裹的元素、缺失的样式、异常的嵌套等）；hyperframes preview启动本地预览，在浏览器中实时确认光扫效果与时间线对齐情况。每次改动组件相关代码后都建议跑一遍 lint，尽早暴露结构性问题。

7. 第 5 步：定制效果

shimmer-sweep 通过 CSS 变量暴露了三个核心定制点，全部可以按元素（per-element）覆盖：

时间线侧的duration、ease、stagger则控制扫动的速度与手感：duration控制单次扫过时长，ease控制加速曲线（power2.inOut是常见的先快后慢再收尾），stagger控制多目标间的起扫间隔。想做出"依次扫过标题每个词"的效果，把每个词各自包进.shimmer-sweep-target并调大stagger即可。

8. 从示例到通用方法：组件接线的四条原则

把 shimmer-sweep 的步骤抽象出来，就是所有组件接线的通用方法论（见 组件接线参考 的 Key principles）：

1. 组件继承宿主合成的尺寸与时长——无需关心独立画布，只管元素在宿主中的层级位置；
2. 把组件 HTML 放在与内容匹配的 z-index——效果层覆盖在目标内容之上，且pointer-events通常关闭，避免挡住交互；
3. 先读片段注释头——每个片段可定制的值都写在注释头里，这是第一手文档；
4. 接线后运行hyperframes lint——用工具兜底结构性问题。

对比另一类纯 CSS 组件（如grain-overlay，用@keyframes做噪点动画，不需要任何 GSAP 调用），可以看到组件之间的差异只在"是否需要时间线集成"：CSS-only 组件粘贴 HTML 与 CSS 即可完成，时间线集成型组件（如 shimmer-sweep）才需要额外的 JS 注入与tl.fromTo调用。判断依据同样是片段注释头。

9. 延伸阅读

• 注册表总览与命令行速查——add、catalog搜索、标签批量安装、gap 反馈的完整语义
• 安装位置与路径重映射——hyperframes.json#paths的完整配置说明
• 组件接线参考——grain-overlay 完整示例与通用原则
• add 命令源码——安装解析、依赖排序、片段生成的实现细节
• hyperframes.json 配置 schema——registry与paths的字段约束

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