企业官网建设流程全解析

HyperFrames 组件接线（Wiring Components）实战指南：将特效片段无缝嵌入宿主合成

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

组件（Components）是 HyperFrames 生态中与块（Blocks）并行的第二种复用单元：它们是"效果片段"——一段包含 HTML、CSS 以及可选 JavaScript 的代码片段，直接合并进你已有的合成（composition）中使用。与块不同，组件没有独立的时长与时间线，而是完全融入宿主合成的时间线，随宿主一起渲染。本文基于 wiring-components.md 梳理组件接线的完整方法论，并结合仓库源码（CLI 实现、注册表 manifest 与真实组件示例）深入讲解安装、合并、时间线集成与校验的全过程。读完你将掌握：如何用hyperframes add安装组件、如何把组件的 HTML/CSS/JS 正确粘贴进宿主合成、如何处理"纯 CSS 动画"与"需 GSAP 时间线驱动"两类组件，以及如何用hyperframes lint与hyperframes preview验证接线结果。

组件与块：两种复用单元的定位差异

在动手接线之前，先明确组件在整个注册表体系中的位置。根据 SKILL.md 的定义：

• 块（Blocks）——独立的子合成（sub-composition），拥有自己的尺寸、时长和时间线，通过宿主合成中的data-composition-src属性引入；
• 组件（Components）——效果片段，没有自己的尺寸与时间线，直接粘贴进宿主合成的 HTML 中。

这一区别直接决定了接线的两种不同姿势：块靠"声明式挂载"（一个带属性的<div>即可），而组件靠"手工合并"（把片段内容复制进宿主文件）。组件清单可以在 discovery.md 的组件表格中查看，包括grain-overlay（胶片颗粒纹理）、shimmer-sweep（文字高光扫过）、morph-text（粘稠文字变形）、grid-pixelate-wipe（网格溶解转场）等。

组件接线的一般流程

组件接线的通用流程在 wiring-components.md 中定义为五个步骤：

1. 安装：运行hyperframes add <component-name>；
2. 打开安装文件：例如compositions/components/grain-overlay.html；
3. 阅读注释头：每个组件片段的顶部注释块会说明用法、可自定义的值及其默认值；
4. 把片段复制进宿主合成，分四类内容各就各位：
   • HTML 元素—— 放进宿主合成的<div><div id="grain-overlay" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;" > <div class="grain-texture"></div> </div>

     CSS 部分——把@keyframes hf-grain-noise与.grain-texture规则粘贴进宿主的样式块。注意两个实现细节：纹理层被放大到200%（top: -50%; left: -50%）并利用translate抖动，从而在平移时不会露出边缘；动画使用steps(1)做逐帧跳变，模拟真正的胶片颗粒闪烁效果，噪点本身由内联 SVG 的feTurbulence滤镜生成，无需任何外部图片资源：

     @keyframes hf-grain-noise { 0%, 100% { transform: translate(0, 0); } 10% { transform: translate(-5%, -5%); } 20% { transform: translate(-10%, 5%); } /* …各关键帧依次跳变… */ 90% { transform: translate(10%, 5%); } } #grain-overlay .grain-texture { position: absolute; top: -50%; left: -50%; width: 200%; height: 200%; background: url("data:image/svg+xml,..."); /* feTurbulence 噪点 */ opacity: 0.15; animation: hf-grain-noise 0.5s steps(1) infinite; }

     接线完成后，该组件不需要任何 GSAP 时间线调用——颗粒动画完全由 CSS 驱动。组件 manifest registry/components/grain-overlay/registry-item.json 证实了它的类型为"hyperframes:component"，文件目标为compositions/components/grain-overlay.html，标签为["texture", "grain", "overlay", "film"]。

     示例二：shimmer-sweep（需要时间线集成）

     shimmer-sweep演示了"HTML + CSS + JS 自动注入 + GSAP 时间线"四件套齐全的组件接线方式，完整演练见 add-component.md。目标场景：给标题文字加一道扫过的光效。

     第 1 步：安装组件

     hyperframes add shimmer-sweep

     第 2 步：读取片段，打开compositions/components/shimmer-sweep.html，其源码见 registry/components/shimmer-sweep/shimmer-sweep.html。

     第 3 步：接入宿主合成，分四部分：

     HTML——用包装元素把目标文字包起来，并通过 CSS 变量定制光效颜色：

     <div class="shimmer-sweep-target" style="--shimmer-color: rgba(255, 255, 255, 0.5)"> <h1 class="title">AI-Powered Video</h1> </div>

     CSS——粘贴片段中的.shimmer-sweep-target与.shimmer-mask规则。核心是.shimmer-mask上由 CSS 变量驱动的线性渐变：--shimmer-pos（扫光位置）配合--shimmer-angle（扫光角度）、--shimmer-width（光带宽度）与--shimmer-color（高光颜色）动态计算透明到高光的渐变带，并叠加mix-blend-mode: overlay让光带自然融入文字：

     .shimmer-sweep-target { position: relative; display: inline-block; } .shimmer-sweep-target .shimmer-mask { position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; background: linear-gradient( var(--shimmer-angle, 120deg), transparent 0%, transparent calc(var(--shimmer-pos, -20%) - var(--shimmer-width, 20%) / 2), var(--shimmer-color, rgba(255, 255, 255, 0.6)) var(--shimmer-pos, -20%), transparent calc(var(--shimmer-pos, -20%) + var(--shimmer-width, 20%) / 2), transparent 100% ); mix-blend-mode: overlay; }

     JS——粘贴自动注入脚本（放在宿主时间线代码之前）。它遍历所有.shimmer-sweep-target元素，为尚未包含.shimmer-mask的元素动态创建遮罩子节点，避免你手写重复的 DOM 结构：

     document.querySelectorAll(".shimmer-sweep-target").forEach((el) => { if (!el.querySelector(".shimmer-mask")) { const mask = document.createElement("div"); mask.className = "shimmer-mask"; el.appendChild(mask); } });

     时间线——在 GSAP 时间线里驱动--shimmer-pos从-20%扫到120%，实现一次完整的左到右扫光。注意这里动画的是 CSS 变量而不是某个 CSS 属性，这正是 HyperFrames 用 GSAP 驱动确定性逐帧渲染的典型手法：

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

     第 4 步：校验与预览

     hyperframes lint hyperframes preview

     第 5 步：自定义。片段注释头列出的可调参数：

     • --shimmer-color：每个元素的高光颜色（默认rgba(255,255,255,0.6)）；
     • --shimmer-width：光带宽度百分比（默认20%）；
     • --shimmer-angle：扫光角度（默认120deg）；
     • 时间线duration/ease/stagger：控制扫光速度与节奏感。

     接线要点与最佳实践

     wiring-components.md 归纳了四条关键原则，接线时应时刻遵守：

     1. 组件继承宿主合成的尺寸与时长——组件本身没有画布尺寸和时长概念，它完全跟随宿主 1920×1080 或你设定的任意画布，渲染时长也由宿主时间线决定；
     2. 按 z-index 摆放组件 HTML——组件以绝对定位叠在宿主内容之上，应结合视觉层级把组件放在合适的z-index，例如grain-overlay使用z-index: 100覆盖全画面，而shimmer-sweep的遮罩是目标元素内部的绝对定位层；
     3. 务必阅读每个片段的注释头——所有可自定义的值（颜色、宽度、角度、速度、层级）都写在注释块里，直接抄片段却不看注释是接线最常见的失误来源；
     4. 接线后运行hyperframes lint——用校验器兜底，捕获结构性问题。

     安装路径与 hyperframes.json 配置

     组件的默认安装位置是compositions/components/<name>.html（块则默认装到compositions/<name>.html）。这个路径可以在hyperframes.json中整体重定义，配置项在 projectConfig.ts 中定义了默认值：

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

     从源码看，路径重映射由 add.ts 中的remapTarget函数完成：对于hyperframes:component类型的条目，它把 manifest 中形如compositions/components/<name>.html的目标前缀替换为用户配置的paths.components，从而让项目可以重塑目录布局，而无需逐个修改每个条目的 manifest。相应的单元测试见 add.test.ts，其中验证了组件默认装入compositions/components/、路径可被paths.components改写，以及buildSnippet对组件输出 "paste from" 粘贴提示、对块输出data-composition-src挂载片段——即安装完成后 CLI 打印的接线提示正是为两种类型分别定制的。

     用 lint 与 preview 验证接线结果

     hyperframes lint用于校验合成中的常见错误。命令本身支持三个参数（见 lint.ts）：

     • hyperframes lint——校验当前项目；
     • hyperframes lint ./my-video——校验指定目录；
     • hyperframes lint --json——以 JSON 输出发现项，适合 CI 与 Agent 工作流；
     • hyperframes lint --verbose——同时显示 info 级发现项（默认隐藏）。

     接线完成后先hyperframes lint再hyperframes preview预览，即可确认组件已正确并入宿主合成：颗粒纹理是否覆盖画面、扫光是否按时间线节奏出现、层级是否被遮挡，这些都能在预览中直接确认。遵循"先读注释头、再分区粘贴、后 lint 校验"的流程，就能把注册表里的任意组件稳定、可复用地接入你的 HyperFrames 项目。

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