HTML Schema 参考

这是 Hyperframes 合成的完整 schema 参考。如需更温和的入门介绍，请参阅合成和数据属性。

概览

Hyperframes 使用 HTML 作为描述视频的权威来源：

• HTML clip = 视频、图像、音频、合成
• 数据属性 = 时序、元数据、样式
• CSS = 定位和外观
• GSAP 时间轴 = 动画和播放同步（参见 GSAP 动画）

框架管理的行为

框架读取数据属性并自动管理：

• 基本 clip 时间轴条目 — 从 clip 中读取 data-start、data-duration 和 data-track-index，并将它们添加到 GSAP 时间轴
• 媒体播放（播放、暂停、跳转）用于 <video> 和 <audio>
• Clip 生命周期 — clip 根据 data-start 和 data-duration 进行挂载/卸载
• 时间轴同步 — 保持媒体与 GSAP 主时间轴同步
• 媒体加载 — 等待所有媒体加载完毕后再解析时序

挂载/卸载控制的是存在性，而非外观。过渡效果（淡入、滑入）在脚本中以动画方式实现。

⚠️ Warning

不要在脚本中手动调用 video.play()、video.pause()、设置 audio.currentTime，或挂载/卸载 clip。框架拥有媒体播放和 clip 生命周期的所有权。更多详情请参阅常见错误。

视口

每个合成必须在根元素上包含 data-width 和 data-height：

<div id="main" data-composition-id="my-video"
data-start="0" data-width="1920" data-height="1080">
<!-- clips -->
</div>

常用尺寸：

• 横向：data-width="1920" data-height="1080"
• 纵向：data-width="1080" data-height="1920"

所有 Clip 属性

Clip 类型

<video
id="el-1"
data-start="0"
data-duration="15"
data-track-index="0"
data-media-start="0"
src="./assets/video.mp4"
></video>

<img
id="el-2"
class="clip"
data-start="5"
data-duration="4"
data-track-index="1"
src="./assets/overlay.png"
/>

<audio
id="el-4"
data-start="0"
data-duration="30"
data-track-index="2"
src="./assets/music.mp3"
></audio>

<div
id="el-5"
data-composition-id="intro-anim"
data-composition-src="compositions/intro-anim.html"
data-start="0"
data-track-index="3"
></div>

相对时序

在 data-start 中引用另一个 clip 的 ID 表示"在该 clip 结束时开始"：

<video id="intro" data-start="0" data-duration="10" data-track-index="0" src="..."></video>
<video id="main" data-start="intro" data-duration="20" data-track-index="0" src="..."></video>

main 在第 10 秒开始（当 intro 结束时）。

偏移量允许你添加间隔或重叠：

<!-- intro 之后 2 秒的间隔 -->
<video id="main" data-start="intro + 2" data-duration="20" data-track-index="0" src="..."></video>

<!-- 与 intro 重叠 0.5 秒 -->
<video id="main" data-start="intro - 0.5" data-duration="20" data-track-index="0" src="..."></video>

更深入的解释请参阅数据属性概念页面中的相对时序部分。

时间轴约定

框架在任何脚本运行之前初始化 window.__timelines = {}。每个合成必须在与其 data-composition-id 匹配的键上注册一个 GSAP 时间轴：

const tl = gsap.timeline({ paused: true });

// 添加动画
l.to("#title", { opacity: 1, duration: 0.5 }, 0);
l.to("#title", { opacity: 0, duration: 0.5 }, 4.5);

// 注册时间轴
window.__timelines["<data-composition-id>"] = tl;

规则

• 每个合成需要一个 <script> 块来创建和注册其时间轴
• 所有时间轴必须以暂停状态开始（{ paused: true }）
• 框架自动将子时间轴嵌套到父时间轴中 — 不要手动添加
• 时长来自 tl.duration() — 不要在合成元素上添加 data-duration
• 时间轴必须是有限的（无无限循环或重复）
• 时间轴 ID 必须与根元素上的 data-composition-id 属性完全匹配

有关使用 GSAP 时间轴的完整指南，请参阅 GSAP 动画。

字幕可发现性

对于字幕合成，在根节点上添加这些属性，以便框架能够识别并特殊处理字幕渲染：

<div
data-composition-id="captions"
data-timeline-role="captions"
data-caption-root="true"
...
>

输出检查清单