> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperframes-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# GSAP动画

> 使用 GSAP 将动画添加到您的HyperFrames合成中。

Hyperframes 使用 [GSAP](https://gsap.com/) 进行动画。时间线由运行时暂停和控制 - 您定义动画，框架处理播放。有关动画运行时如何插入HyperFrames的背景信息，请参阅[帧适配器](/concepts/frame-adapters)。

## 设置

包括 GSAP 并创建暂停的时间线：

```html index.html theme={null}
<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>
```

<Note>
  您在 `window.__timelines` 中使用的密钥必须与合成根元素上的 `data-composition-id` 属性匹配。请参阅 [Compositions](/concepts/compositions) 了解根元素的结构。
</Note>

## 关键规则

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`](/concepts/data-attributes#composition-attributes) 作为键在 `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 时间线持续时间。两者是直接相连的：

```javascript compositions/intro-anim.html theme={null}
// 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 秒长，视频将被剪短。要延长时间线以匹配视频：

```javascript index.html theme={null}
// 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);
```

<Warning>
  这是HyperFrames中最常见的错误之一。如果您的视频提前结束，则说明时间线太短。有关更多详细信息，请参阅[常见错误：构图持续时间短于视频](/guides/common-mistakes)。
</Warning>

## 不该做什么

这些模式会破坏您的合成或导致同步问题：

```javascript index.html theme={null}
// 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);
```

该框架自动管理[媒体播放](/reference/html-schema#framework-managed-behavior)、[剪辑生命周期](/concepts/compositions#two-layers-primitives-and-scripts)和[子合成嵌套](#sub-composition-timelines)。重复此行为的脚本将会发生冲突。

## 子作文时间线

每个[嵌套组合](/concepts/compositions#nested-compositions) 注册自己的时间线。框架根据 [`data-start`](/concepts/data-attributes#timing-attributes) 自动将子组合时间线嵌套到父级中：

```javascript compositions/intro-anim.html theme={null}
// 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
```

<Warning>
  不要直接在 `<video>` 元素上设置 `width`、`height`、`top` 或 `left` 的动画 - 这可能会导致浏览器停止渲染帧。将视频包装在 `<div>` 中并为包装器设置动画。请参阅[常见错误](/guides/common-mistakes) 了解详细说明。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="作文" icon="layer-group" href="/concepts/compositions">
    了解时间轴动画的构建块
  </Card>

  <Card title="框架适配器" icon="plug" href="/concepts/frame-adapters">
    了解 GSAP 如何插入渲染管道
  </Card>

  <Card title="常见错误" icon="triangle-exclamation" href="/guides/common-mistakes">
    避免破坏动画的陷阱
  </Card>

  <Card title="HTML 架构参考" icon="code" href="/reference/html-schema">
    组合属性的完整参考
  </Card>
</CardGroup>