HyperFrames 核心
HyperFrames 通过 HTML 渲染视频。合成是一个 HTML 文件,其 DOM 使用 data-* 属性声明时序,动画运行时是可跳转的,媒体播放由框架拥有。
本技能是 技术合约——如何构建一个 hyperframes 项目。正文是构建指南;每个主题的详细信息位于 references/ 中(索引见下方),按需阅读。其他问题位于同级的领域技能中——hyperframes-animation、hyperframes-creative、hyperframes-media、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力映射说明了每个技能的覆盖范围。
参考文件
| 文件 | 阅读目的 |
|---|---|
references/minimal-composition.md | 从最小的可渲染合成框架开始 |
references/composition-patterns.md | 选择整体式 vs 模块化;构建模块化 index.html;选择子合成原型 |
references/data-attributes.md | 查找任何 data-*(根 / clip / 子合成宿主 / 旧别名);使用 class="clip" |
references/tracks-and-clips.md | 选择 data-track-index,处理同轨道重叠 / z-index,使一个剪辑相对于另一个剪辑计时 |
references/sub-compositions.md | 连接子合成(宿主属性、<template>、每个实例的变量)并在其内部制作动画 |
references/variables-and-media.md | 声明变量;放置 <video>/<audio>,设置音量,修剪 |
references/determinism-rules.md | 构建可跳转的时间线;确定性禁令;可动画属性白名单;布局 / 文本适配 |
references/full-screen-motion.md | 使用共享背景创作全画幅动画 |
references/storyboard-format.md | 创作 STORYBOARD.md 计划(+ 解析后的清单) |
references/script-format.md | 创作可选的 SCRIPT.md 锁定旁白 |
references/subagent-dispatch.md | 将子代理分发动词(并行扇出 / 后台 / 等待)映射到你的工作流 |
references/tailwind.md | 在 Tailwind v4 项目中工作(init --tailwind;运行时合约与 Studio 的 v3 不同) |
有关动画运行时的详细信息(GSAP API、Lottie、Three.js 等),请前往 hyperframes-animation → adapters/<runtime>.md。
构建合成
两种根形式(不可互换)
- 独立(顶级
index.html)——根<div data-composition-id="…">直接位于<body>中,没有<template>包装(包装会隐藏所有内容并破坏渲染)。 - 子合成(通过
data-composition-src加载)——根 必须 包含在<template>中。
⚠ 传输规则:运行时 只克隆
<template>的内容;外部的一切(包括<head>中的样式/脚本)都会被丢弃——请将<style>/<script>放在 模板内部。 ⚠ 宿主 ID 规则:宿主插槽的data-composition-id必须 完全等于 内部模板的data-composition-id以及window.__timelines["<id>"]的键——不能有-mount/-slot/-host后缀。
文件结构、宿主连接和渲染前检查清单 → references/sub-compositions.md。
根必须有大小(静默布局 Bug)
独立根需要一个明确的 尺寸框(width/height 单位为 px),并且直到 height:100% 元素的每个祖先都必须有已解析的高度——否则 flex/100% 子元素会折叠到约 0,内容堆叠到左上角。lint/validate/inspect 不会 捕获此问题。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个合成注册 恰好一个 gsap.timeline({ paused: true }) 为 window.__timelines["<id>"](键 = 根 data-composition-id),在页面加载时 同步 构建。渲染时长 = 根 data-duration,而不是时间线长度。不要手动将子时间线嵌套到宿主中。完整合约(包括非 GSAP 运行时)→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可协商的规则(lint/validate/inspect 不会捕获的静默 Bug)
在此处列出;完整原理在引用的参考文件中。不要违反:
- 没有运行时时钟 / 未种子的
Math.random/ 网络 / 输入状态;没有repeat: -1(使用有限次数)。→determinism-rules.md - 仅对视觉属性白名单进行动画处理;永远不要使用
display/visibility;不要对后面场景的剪辑使用gsap.set。→determinism-rules.md - 正文文本中不要使用
<br>;变形元素必须是块级且已调整大小;脉动的绝对装饰元素需要峰值间隙。→determinism-rules.md <video>/<audio>必须是 宿主根的直接子元素(永远不要放在子合成<template>/包装器中);框架拥有播放控制权。→variables-and-media.md- 每个
id在 组装后的 页面中必须是唯一的;在子合成内部,使用合成 ID 作为 id 的前缀(#<id>-hero)。重复的<video>/<img>id 会渲染为 空白——生成器通过getElementById注入帧,跨文件重复会绕过lint。→composition-patterns.md - 全屏场景填充应放在一个全出血的 子元素 上(
position:absolute; inset:0),永远不要放在合成根本身——生成器的帧合成可能会丢弃根元素自身的background(帧渲染为 黑色),即使预览/snapshot显示正确。→composition-patterns.md
编辑现有合成
- 首先读取文件。保留无关的时序、轨道、ID、变量、媒体路径。
- 匹配现有的合成 ID 和时间线键。
- 添加剪辑:选择一个不重叠的
data-track-index或有意调整周围的时序。 - 添加子合成:在连接宿主之前验证其内部
data-composition-id。
验证
使用 hyperframes-cli 了解命令详情
-
npx hyperframes lint通过(0 错误) -
npx hyperframes validate通过(0 控制台错误) -
npx hyperframes inspect通过(0 错误) - 包含子合成的项目:
npx hyperframes snapshot --at <midpoints>并目视检查每一帧 -
npx hyperframes preview用于审查(用户可以在 Studio 的时间线中编辑任何内容) -
npx hyperframes render仅在用户批准后执行