Skip to main content
Hyperframes 使用 GSAP 进行动画。时间线由运行时暂停和控制 - 您定义动画，框架处理播放。有关动画运行时如何插入HyperFrames的背景信息，请参阅帧适配器。

​
设置

包括 GSAP 并创建暂停的时间线：
index.html
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
  // 1. Create a paused timeline — the framework controls playback
  const tl = gsap.timeline({ paused: true });

  // 2. Add animations using the position parameter (3rd arg) for absolute timing
  tl.to("#title", { opacity: 1, duration: 0.5 }, 0);

  // 3. Initialize the global timelines registry (if not already present)
  window.__timelines = window.__timelines || {};

  // 4. Register the timeline using the data-composition-id as the key
  window.__timelines["root"] = tl;
</script>
您在 window.__timelines 中使用的密钥必须与合成根元素上的 data-composition-id 属性匹配。请参阅 Compositions 了解根元素的结构。

​
关键规则

  1. Error 500 (Server Error)!!1500.That’s an error.There was an error. Please try again later.That’s all we know.
  2. 以 data-composition-id 作为键在 window.__timelines 上注册时间线
  3. 使用位置参数（第三个参数）进行绝对计时：tl.to(el, vars, 1.5)
  4. Error 500 (Server Error)!!1500.That’s an error.There was an error. Please try again later.That’s all we know.

​
支持的方法

方法描述
tl.to(target, vars, position)Error 500 (Server Error)!!1500.That’s an error.There was an error. Please try again later.That’s all we know.
tl.from(target, vars, position)根据值制作动画
tl.fromTo(target, fromVars, toVars, position)从/到值进行动画处理
tl.set(target, vars, position)立即设定值

​
支持的属性

opacity、x、y、scale、scaleX、scaleY、rotation、width、height、visibility、 color、backgroundColor 和任何 CSS 可动画属性。

​
时间轴持续时间和合成持续时间

合成的持续时间等于其 GSAP 时间线持续时间。两者是直接相连的：
compositions/intro-anim.html
// Your last animation ends at 3 seconds...
tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
tl.to("#title", { opacity: 0, duration: 1 }, 2);
// ...so this composition is exactly 3 seconds long.
如果您的合成包含一个长 283 秒的视频剪辑，但您的最后一个 GSAP 动画在 8 秒结束，则合成将只有 8 秒长，视频将被剪短。要延长时间线以匹配视频：
index.html
// All your visual animations
tl.to("#lower-third", { left: -640, duration: 0.6 }, 7.2);

// Extend the timeline to 283 seconds to match the video length.
// This adds a zero-duration tween at 283s without affecting any elements.
tl.set({}, {}, 283);
这是HyperFrames中最常见的错误之一。如果您的视频提前结束，则说明时间线太短。有关更多详细信息，请参阅常见错误：构图持续时间短于视频。

​
不该做什么

这些模式会破坏您的合成或导致同步问题：
index.html
// WRONG: Playing media in scripts — the framework owns media playback
document.getElementById("el-video").play();
document.getElementById("el-audio").currentTime = 5;

// WRONG: Creating a non-paused timeline
const tl = gsap.timeline(); // missing { paused: true }!

// WRONG: Animating dimensions directly on a <video> element
tl.to("#el-video", { width: 500, height: 280 }, 5);

// WRONG: Manually nesting sub-timelines
const masterTL = window.__timelines["root"];
masterTL.add(window.__timelines["intro-anim"], 0);
该框架自动管理媒体播放、剪辑生命周期和子合成嵌套。重复此行为的脚本将会发生冲突。

​
子作文时间线

每个嵌套组合 注册自己的时间线。框架根据 data-start 自动将子组合时间线嵌套到父级中：
compositions/intro-anim.html
// In compositions/intro-anim.html
const tl = gsap.timeline({ paused: true });
tl.from(".title", { opacity: 0, y: -50, duration: 1 });
window.__timelines["intro-anim"] = tl;

// DO NOT manually add sub-timelines to the master:
// masterTL.add(window.__timelines["intro-anim"], 0); // UNNECESSARY
不要直接在 <video> 元素上设置 width、height、top 或 left 的动画 - 这可能会导致浏览器停止渲染帧。将视频包装在 <div> 中并为包装器设置动画。请参阅常见错误 了解详细说明。

​
下一步

作文

了解时间轴动画的构建块

框架适配器

了解 GSAP 如何插入渲染管道

常见错误

避免破坏动画的陷阱

HTML 架构参考

组合属性的完整参考