HyperFrames Registry 组件 demo.html 规范：从预览渲染到可引用使用示例的完整实践-二趣网

HyperFrames Registry 组件 demo.html 规范：从预览渲染到可引用使用示例的完整实践

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

本指南基于 HyperFrames 仓库中 demo-html-pattern.md 展开，系统讲解 registry 组件为何必须随附demo.html、demo 文件的骨架结构与命名约定、它与组件 snippet 的职责划分，以及 CI 预览管线如何消费 demo 生成目录缩略图与预览视频。读完本文，你将掌握为组件编写合规 demo 的完整模板、真实仓库中的参考实现，以及 demo 与 snippet 之间"预览用 demo、安装用 snippet"的分工边界。

为什么组件要随附 demo.html

在 HyperFrames 的 registry 体系中，每个组件（component）除了交付核心的 effect snippet 之外，还必须随附一个同名的demo.html文件。这个约定同时服务两个目的：

预览夹具（Preview fixture）——CI 预览管线会渲染 demo 文件，为目录文档页（catalog docs page）生成缩略图与预览视频。没有 demo，组件在目录里就没有可视化预览。
使用示例（Usage example）——demo 将组件效果应用在具有代表性的内容上，展示"这个效果应该怎么用"，是作者与使用者都能对照的活的参考实现。

这一点在源码中也有印证：scripts/generate-catalog-previews.ts 的注释明确区分了两类条目的渲染入口："Blocks: renders the block's standalone HTML via a wrapper index.html"与"Components: renders the component's demo.html via a wrapper index.html"——即块渲染自身 HTML，组件则渲染 demo.html，两者都会套一层 wrapper 用于预览捕获。

demo 的骨架结构

一份 demo 是完整、独立的 HTML 合成（composition），典型结构如下：

<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=1920, height=1080" /> <title>Component Name — Demo</title> <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script> <style> /* reset + canvas size */ </style> </head> <body> <div>data-composition-id为<component-name>-demo，且与window.__timelines的注册键完全一致声明data-width="1920"、data-height="1080"、data-duration（5–8 秒），viewport meta 与画布一致
GSAP 以gsap.timeline({ paused: true })创建，动画确定性可复现（无Math.random()、无Date.now()，与 contributing.md 的块级要求一致）
snippet 的 CSS/JS 全部内联，demo 可独立在浏览器打开并播放
若 snippet 声明了data-composition-variables，demo 不重复声明变量，且保留组件自身的 class 以便变量脚本寻址
演示内容具有代表性（真实文案、真实数据形态），并遵守 placeholder-material.md 的占位内容规范
通过hyperframes lint与hyperframes check --no-contrast校验（详见 contributing.md 的 Validate 步骤）
延伸阅读
组件贡献完整流程与质量门禁
块与组件的模板与 registry-item.json 模板
组件质量要求
Registry 技能总览与安装/接线说明
预览管线实现：scripts/generate-catalog-previews.ts
变量组件与 demo 的叠加机制：scripts/catalog/component-variables.ts
【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析