API使用

`gsap.to、from、toFrom()`

GreenSock Animation Platform (GSAP) 的配置属性。以下是 GSAP 核心 API（如 gsap.to(), gsap.from() 等） 中常用 config 属性的整理

属性名	类型	默认值	描述
`duration`	Number	`0.5`	动画持续时间（秒）。
`ease`	String/Function	`"none"`	缓动效果，如 `"power1.inOut"`、`"bounce"` 或自定义函数。
`delay`	Number	`0`	动画开始前的延迟时间（秒）。
`repeat`	Number	`0`	动画重复次数（`-1` 表示无限重复）。
`repeatDelay`	Number	`0`	每次重复之间的延迟时间（秒）。
`yoyo`	Boolean	`false`	是否反向重复动画（类似“往返”效果）。
`onComplete`	Function	`null`	动画完成时的回调函数。
`onStart`	Function	`null`	动画开始时的回调函数。
`onUpdate`	Function	`null`	动画每次更新时的回调函数。
`onRepeat`	Function	`null`	动画每次重复时的回调函数。
`immediateRender`	Boolean	`true`*	是否立即渲染初始状态（`gsap.from()` 默认为 `true`，其他为 `false`）。
`overwrite`	String/Boolean	`"auto"`	控制动画冲突的覆盖模式，可选 `"auto"`、`true`、`false` 等。
`paused`	Boolean	`false`	是否在创建时暂停动画。
`lazy`	Boolean	`true`	是否延迟渲染以提高性能（在复杂场景中自动优化）。
`repeatRefresh`	Boolean	`false`	是否在每次重复时重新计算起始值（适用于动态变化的值）。
`defaults`	Object	`null`	为子动画设置默认属性（常用于时间线嵌套）。
`keyframes`	Array/Object	`null`	定义关键帧动画（按顺序执行多个动画属性）。

gsap.to(".box", {
  // --- 基础动画属性 --- x/y 的坐标系：浏览器左上角为原点 (0,0)
  x: 100,           // 横向移动（正数向右，负数向左）
  y: -50,           // 纵向移动（正数向下，负数向上）
  xPercent: -50,    // (百分比%) 向左移动自身宽度的50%（常用于水平居中）
  yPercent: -50,    // (百分比%) 向上移动自身高度的50%（常用于垂直居中）
  rotation: 45,     // 旋转角度（单位：度）
  opacity: 0.5,     // 透明度（0完全透明，1不透明）
  scale: 1.5,       // 缩放比例（1为原大小）

  // --- 时间控制 ---
  duration: 1,       // 动画持续时间（秒）
  delay: 0.5,        // 开始前的延迟时间（秒）
  repeat: 2,         // 重复次数（-1为无限循环） 使用 rotation 而非 rotate（GSAP 专用属性）
  repeatDelay: 1,    // 每次重复前的延迟时间（秒）
  yoyo: true,        // 重复时是否反向播放（需配合 repeat 使用）
    
  // --- 路径动画 ---
  motionPath: {
    path: "#svg-path",   // 沿SVG路径运动
    align: "#svg-path"   // 元素对齐路径方向
  },

    
  // --- 运动曲线 ---
  // 查看所有缓动：https://greensock.com/docs/v3/Eases
  ease: "power2.inOut", // 缓动函数（其他选项：back, elastic, bounce...）
  
  // --- 回调函数 ---
  onStart: () => {   // 动画开始时触发
    console.log("动画开始！");
  },
  onUpdate: (self) => { // 每帧更新时触发
    console.log("进度:", self.progress.toFixed(2));
  },
  onRepeat: () => {  // 每次重复时触发
    console.log("动画重复！");
  },
  onComplete: () => { // 动画完成时触发
    console.log("动画完成！");
  },

  // --- 高级控制 ---
  overwrite: "auto",  // 自动处理属性冲突（推荐）
  paused: false,      // 创建后是否暂停
  lazy: false,        // 关闭延迟渲染（强制立即计算初始值），对大量元素动画启用 `lazy: true`
  repeatRefresh: true,// 每次重复时重新计算初始值（适合动态目标）
  
  // --- 关键帧动画 ---
  keyframes: [        // 多段动画按顺序执行
    { x: 200, duration: 0.5 }, // 第一阶段：0.5秒内移动到x200
    { y: 100, duration: 1 }     // 第二阶段：1秒内移动到y100
  ]
});

/***​ 重点说明 ​**
4. 关键帧技巧：
   - 可用 `stagger` 实现错开动画
   - 时间轴嵌套：结合 `gsap.timeline()` 管理复杂序列
***/

更完整的配置表

基础动画属性

属性名	类型	默认值	描述
`x`	Number	-	横向平移（像素单位，正数向右）
`y`	Number	-	纵向平移（像素单位，正数向下）
`xPercent`	Number	-	横向平移百分比（基于元素自身宽度，`xPercent: -50` 左移50%宽度）
`yPercent`	Number	-	纵向平移百分比（基于元素自身高度，`yPercent: -50` 上移50%高度）
`rotation`	Number	-	旋转角度（单位：度）
`scale`	Number	1	整体缩放比例
`opacity`	Number	1	透明度（0-1）

// 水平垂直居中元素
gsap.set(".box", {
  xPercent: -50,
  yPercent: -50,
  x: "50%",   // 相对于父元素
  y: "50%"
});

// 多个元素依次动画
gsap.to(".item", {
  x: 100,
  stagger: 0.2,              // 每个元素间隔0.2秒
    
  // 或复杂配置
  stagger: {
    amount: 1,              // 总错开时间1秒
    from: "center"          // 从中心向两侧启动
  }
});

高级变换属性

属性名	类型	描述
`rotationX`	Number	3D X轴旋转角度（单位：度）
`rotationY`	Number	3D Y轴旋转角度
`skew`	Number	倾斜角度（单位：度）
`skewX`	Number	单独X轴倾斜角度
`skewY`	Number	单独Y轴倾斜角度
`transformOrigin`	String	变换原点（如 `"center center"` 或 `"left top"`）

时间与重复控制

属性名	类型	描述
`repeat`	Number	重复次数（`-1` 表示无限循环）
`repeatDelay`	Number	每次重复前的延迟时间（秒）
`yoyo`	Boolean	是否反向重复动画
`repeatRefresh`	Boolean	每次重复时重新计算初始值（适用于动态目标）

回调函数

属性名	类型	触发时机
`onStart`	Function	动画开始时
`onUpdate`	Function	每帧更新时（参数为动画实例）
`onRepeat`	Function	每次重复时
`onComplete`	Function	动画完成时
`onReverseComplete`	Function	反向播放完成时
`onInterrupt`	Function	动画被中断时（如手动暂停或被覆盖）

高级控制

属性名	类型	描述
`overwrite`	String/Boolean	动画冲突覆盖策略（`"auto"`、`true`、`false`）
`lazy`	Boolean	延迟渲染（默认 `true`，复杂场景自动优化性能）
`immediateRender`	Boolean	是否立即渲染初始状态（`gsap.from()` 默认为 `true`）
`keyframes`	Array/Object	关键帧动画（按顺序执行多段动画）
`stagger`	Number/Object	错开动画（多个元素依次延迟启动，如 `stagger: 0.1`）
`motionPath`	Object/Array	沿路径运动（定义SVG路径或坐标点）

gsap.to(".car", {
  duration: 5,
  motionPath: {
    path: [{x:0, y:0}, {x:300, y:100}, {x:500, y:-50}], // 坐标点路径
    curviness: 1.5        // 路径平滑度
  }
});

特殊属性

属性名	类型	描述
`autoAlpha`	Number	同时控制 `opacity` 和 `visibility`（0时自动设为 `visibility: hidden`）
`scrollTrigger`	Object	绑定滚动触发动画（需配合 ScrollTrigger 插件）
`inherit`	Boolean	是否继承父级动画的属性（默认 `true`，时间线嵌套时自动继承）
`id`	String	为动画添加ID（便于后续查找或控制）

`gsap.context()`

Context 是 GSAP 3.11+ 引入的核心功能，专门用于简化动画的生命周期管理和作用域控制，尤其在 React/Vue 等框架中非常有用。

核心作用

自动清理 - 组件卸载时自动回收所有关联动画
作用域隔离 - 限定选择器的作用范围，避免全局冲突
批量管理 - 统一管理多个动画和滚动触发器
内存优化 - 防止内存泄漏

React中的典型应用

import { useRef, useEffect } from "react";
import gsap from "gsap";

const MyComponent = () => {
  const containerRef = useRef<HTMLDivElement>(null);
  
  // 使用GSAP Context
  useEffect(() => {
    const ctx = gsap.context(() => {
      // 所有动画在此创建（作用域限定在containerRef内）
      gsap.to(".box", { 
        x: 100,
        scrollTrigger: {
          trigger: ".box",
          toggleActions: "restart pause resume pause"
        }
      });
      
      gsap.from(".text", { 
        opacity: 0,
        duration: 2 
      });

    }, containerRef); // 限定作用域

    return () => ctx.revert(); // 组件卸载时自动清理
  }, []);

  return (
    <div ref={containerRef}>
      <div className="box"></div>
      <p className="text">Hello World</p>
    </div>
  );
};

`gsap.timeline(options)`

核心概念

默认行为 时间轴中的动画默认按顺序执行（前一个动画结束后，后一个开始）。
时间控制 可插入延迟、重叠动画，或通过时间戳精准控制。
复用性 时间轴可保存为变量，随时调用、暂停、反转或重复。

配置详解

gsap.timeline({
  // 基础控制
  repeat: 2,           // 重复次数，默认0，类型：number，场景：轮播/循环动画
  repeatDelay: 1,      // 重复前延迟秒数，默认0，类型：number，场景：循环间隔
  paused: true,        // 初始暂停状态，默认false，类型：boolean，场景：手动控制播放
  delay: 0.5,          // 初始延迟秒数，默认0，类型：number，场景：延迟启动

  // 动画行为
  yoyo: true,          // 往返播放，默认false，类型：boolean，场景：元素来回运动
  yoyoEase: "power1",  // 往返缓动，默认原动画缓动，类型：string|function，场景：调整往返速度曲线
  defaults: {          // 子动画默认参数，默认{}，类型：object，场景：统一动画配置
    duration: 1, 
    ease: "sine.out"
  },

  // 回调函数
  onComplete: () => console.log("done"),  // 完成回调，默认null，类型：function，场景：结束事件
  onStart: () => console.log("start"),    // 开始回调，默认null，类型：function，场景：启动事件
  onUpdate: () => console.log("update"),  // 更新回调，默认null，类型：function，场景：实时进度监控
  onRepeat: () => console.log("repeat"),  // 重复回调，默认null，类型：function，场景：统计重复次数

  // 高级控制
  smoothChildTiming: false, // 子动画动态时序，默认true，类型：boolean，场景：固定时序性能优化
  autoRemoveChildren: true, // 自动移除子动画，默认false，类型：boolean，场景：内存管理
  id: "pageAnim"            // 时间轴ID，默认null，类型：string，场景：动画检索/控制
});

基础使用

1. 创建时间轴并添加动画

// 创建时间轴
const tl = gsap.timeline();

// 添加动画（顺序执行）
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 50, duration: 0.5 })
  .to(".box3", { opacity: 0, duration: 2 });

执行顺序：box1 移动 → box2 移动 → box3 渐隐，总时长 1 + 0.5 + 2 = 3.5秒。

2. 并行动画（重叠执行）

使用 position 参数指定动画插入的时间点：

const tl = gsap.timeline();
tl.to(".box1", { x: 100, duration: 1 })
  .to(".box2", { y: 50, duration: 2 }, "<")      // 与上一个动画同时开始（"<" 表示重叠）
  .to(".box3", { opacity: 0, duration: 1 }, "<1"); // 在上一个动画开始后1秒启动

box1 和 box2 同时启动，box3 在 box2 启动后1秒开始。

进阶功能

3. 时间轴参数配置

创建时间轴时传入配置对象：

const tl = gsap.timeline({
  repeat: 2,          // 重复2次
  repeatDelay: 1,    // 每次重复间隔1秒
  paused: true,       // 默认暂停，需手动启动
  onComplete: () => console.log("动画完成!")
});

4. 使用标签（Labels）精准控制

const tl = gsap.timeline();
tl.add("start")                       // 定义标签 "start"
  .to(".box1", { x: 100, duration: 1 })
  .add("mid", "+=0.5")                // 在上一动画结束后0.5秒插入标签 "mid"
  .to(".box2", { y: 50, duration: 1 }, "mid")  // 在 "mid" 标签处插入动画
  .to(".box3", { opacity: 0 }, "start+=2");    // 在 "start" 标签后2秒执行

5. 嵌套时间轴

时间轴可以嵌套其他时间轴，实现模块化动画：

const childTl = gsap.timeline();
childTl.to(".child", { scale: 1.5, duration: 1 })
       .to(".child", { rotation: 360, duration: 2 });

const parentTl = gsap.timeline();
parentTl.to(".parent", { x: 200, duration: 2 })
        .add(childTl)      // 将子时间轴添加到父时间轴
        .to(".parent", { opacity: 0, duration: 1 });

复杂场景示例

6. 精确控制动画位置

const tl = gsap.timeline();
tl.to(".a", { x: 100, duration: 2 })
  .to(".b", { y: 50, duration: 1 }, "-=1")   // 在动画a结束前1秒开始
  .to(".c", { opacity: 0 }, "+=0.5")         // 在动画b结束后0.5秒开始
  .to(".d", { scale: 2 }, 3);               // 在时间轴的第3秒插入

7. 回调函数与事件监听

const tl = gsap.timeline({
  onStart: () => console.log("时间轴开始"),
  onUpdate: () => console.log("时间轴更新中"),
});

tl.to(".box", { x: 100, duration: 1 })
  .add(() => console.log("动画完成!"), "+=0.5"); // 延迟0.5秒后触发回调

时间轴控制方法

const tl = gsap.timeline();

// 控制方法
tl.play();      // 播放
tl.pause();     // 暂停
tl.reverse();   // 反向播放
tl.seek(2);     // 跳转到第2秒
tl.progress(0.5); // 跳转到总进度的50%
tl.kill();      // 销毁时间轴

最佳实践

模块化设计 将复杂动画拆分为多个子时间轴，提高代码可维护性。
合理使用标签 用标签替代硬编码时间值，更易调整时序。
性能优化 避免在时间轴中频繁操作DOM，利用 gsap.context() 管理作用域。

实例API

const tl = gsap.timeline();

// ==== 播放控制 ====
tl.play();              // 播放动画 ▶️
tl.pause();             // 暂停动画 ⏸️
tl.reverse();           // 反向播放动画 ⏪
tl.resume();            // 从暂停处继续播放 ⏯️
tl.restart();           // 重新开始播放 🔄
tl.seek(2);             // 跳转到第2秒或标签位置 🎯 | 参数：(时间秒数/标签名)

// ==== 状态判断 ====
tl.progress();          // 获取当前进度(0~1) 📊 | 参数：空(获取) / 0.5(设置进度)
tl.time();              // 获取当前时间(秒数) ⏱️ | 参数：空(获取) / 3(设置时间)
tl.isActive();          // 是否正在播放中 🚦 | 返回：true/false
tl.reversed();          // 是否处于反向状态 🔙 | 返回：true/false
tl.duration();          // 获取总时长(秒) ⏳ | 参数：false(不包含重复次数) 
tl.totalDuration();     // 总时长(含所有重复次数) ⏳⏳

// ==== 子动画管理 ====
tl.add( gsap.to(...) );  // 添加动画/回调 ➕ | 参数：(动画实例/函数, 插入位置)
tl.getChildren();       // 获取所有子动画列表 📜
tl.remove( child );     // 删除指定子动画 ➖ | 参数：动画实例
tl.clear();             // 清空所有子动画 🧹 (保留配置)

// ==== 时间轴标记 ====
tl.addLabel("start");   // 添加时间轴标签 🏷️ | 参数：(标签名, 时间位置)
tl.removeLabel("end");  // 删除指定标签 🗑️

// ==== 回调控制 ====
tl.call( () => {} );    // 插入回调函数 📞 | 参数：(函数, 参数数组, 插入位置)
tl.eventCallback("onComplete", () => {}); // 设置事件回调 🎫 | 支持事件类型：onStart/Update/Complete/Repeat

// ==== 高级操作 ====
tl.kill();              // 销毁时间轴并释放内存 💀 (不可逆操作)
tl.invalidate();        // 重置初始值 🔄 (用于动态修改后重新播放)
tl.set( {x: 100} );     // 立即设置属性 ⚡ | 参数：(目标对象, 属性值)

gsap.to、from、toFrom()​

更完整的配置表​

基础动画属性​

高级变换属性​

时间与重复控制​

回调函数​

高级控制​

特殊属性​

gsap.context()​

核心作用​

React中的典型应用​

gsap.timeline(options)​

核心概念​

配置详解​

基础使用​

1. 创建时间轴并添加动画​

2. 并行动画（重叠执行）​

进阶功能​

3. 时间轴参数配置​

4. 使用标签（Labels）精准控制​

5. 嵌套时间轴​

复杂场景示例​

6. 精确控制动画位置​

时间轴控制方法​

最佳实践​

实例API​