gsap 配置解读 --7

什么是registerEffect

 <div class="card">
      <h1>案例 41：registerEffect 自定义效果</h1>
      <p>封装常用动画为可复用效果。</p>
      <div class="row">
        <div class="box" id="boxA"></div>
        <div class="box" id="boxB"></div>
        <div class="box" id="boxC"></div>
      </div>
      <button id="play">播放效果</button>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
    <script>
      const playButton = document.querySelector("#play");

      // 注册自定义效果
      gsap.registerEffect({
        name: "popIn",
        effect: (targets, config) => {
          return gsap.fromTo(
            targets,
            { scale: 0.6, opacity: 0 },
            {
              scale: 1,
              opacity: 1,
              duration: config.duration,
              stagger: config.stagger,
              ease: config.ease
            }
          );
        },
        defaults: { duration: 0.6, stagger: 0.08, ease: "back.out(1.6)" },
        extendTimeline: true
      });

      playButton.addEventListener("click", () => {
        gsap.effects.popIn(".box");
      });
    </script>

gsap.registerEffect() 是 GSAP（GreenSock Animation Platform） 提供的一个强大功能，用于将常用的动画逻辑封装成可复用、可配置的"自定义效果"（custom effect），就像创建自己的动画"函数库"一样。

---

📌 简单定义：

registerEffect 允许你定义一个命名动画模板（如 "popIn"），之后通过 gsap.effects.effectName(targets, config) 一行代码即可在任意地方调用它，实现代码复用、语义化和团队协作标准化。

---

✅ 核心作用：

1. 封装复杂动画逻辑

把重复的 fromTo、timeline 等逻辑打包成一个"黑盒"。

2. 支持参数配置

通过 config 对象传入自定义参数（如 duration、stagger）。

3. 提供默认值

通过 defaults 设置常用参数的默认值，调用时可省略。

4. 无缝集成 GSAP 生态

• 可用于 Timeline
• 支持 stagger
• 返回动画实例（可 play/pause/reverse）

---

🔧 在你的代码中：

gsap.registerEffect({
  name: "popIn", // 效果名称
  effect: (targets, config) => {
    return gsap.fromTo(
      targets,
      { scale: 0.6, opacity: 0 },
      {
        scale: 1,
        opacity: 1,
        duration: config.duration,
        stagger: config.stagger,
        ease: config.ease
      }
    );
  },
  defaults: { 
    duration: 0.6, 
    stagger: 0.08, 
    ease: "back.out(1.6)" 
  },
  extendTimeline: true // 允许在 Timeline 中直接使用 .popIn()
});

然后调用：

gsap.effects.popIn(".box"); // 所有 .box 元素执行 popIn 动画

效果：

• 三个盒子依次从小且透明放大到正常尺寸；
• 带有弹性回弹（back.out 缓动）；
• 每个盒子延迟 0.08s 启动（stagger）。

---

🌟 优势 vs 普通函数封装：

普通函数	registerEffect
需手动管理返回值	✅ 自动注册到 gsap.effects 命名空间
无法在 Timeline 中直接使用	✅ 开启 extendTimeline: true 后可用 tl.popIn(...)
参数处理需自己写	✅ 自动合并 config 与 defaults
团队协作需文档说明	✅ 效果名称即文档（gsap.effects.popIn 语义清晰）

---

⚙️ 参数详解：

字段	说明
name	效果名称（字符串），注册后可通过 gsap.effects[name] 调用
effect(targets, config)	动画工厂函数： - targets: DOM 元素或选择器 - config: 用户传入的配置对象
defaults	默认配置（会被 config 覆盖）
extendTimeline	若为 true，可在 Timeline 实例上直接调用该效果： timeline.popIn(".box")

---

🛠️ 更多使用方式：

1. 传入自定义参数

gsap.effects.popIn(".item", {
  duration: 1,
  stagger: 0.2,
  ease: "elastic.out(1, 0.5)"
});

2. 在 Timeline 中使用（需 extendTimeline: true）

const tl = gsap.timeline();
tl.popIn(".box", { duration: 0.5 });

3. 返回 Timeline 实现复杂效果

effect: (targets) => {
  const tl = gsap.timeline();
  tl.from(targets, { x: -100, opacity: 0 })
    .to(targets, { rotation: 360 }, "<");
  return tl;
}

---

🎨 典型应用场景：

• UI 组件库：统一按钮点击、卡片入场、提示弹出等动效
• 设计系统：确保全站动画风格一致
• 游戏开发：角色受伤、道具拾取等特效复用
• 快速原型：设计师给效果命名，开发者一键实现

---

⚠️ 注意事项：

• 效果名称全局唯一，避免冲突；
• targets 可以是单个元素、数组或 CSS 选择器字符串；
• 免费功能 ：registerEffect 是 GSAP 核心 API，无需额外插件或会员；
• 如果效果内部使用了 ScrollTrigger 等插件，需确保已注册。

---

📚 官方文档：

👉 greensock.com/docs/v3/GSA...

---

✅ 总结：

gsap.registerEffect() 是 GSAP 的"动画组件化"方案------它将零散的动画代码提炼为可命名、可配置、可复用的效果模块，大幅提升开发效率与代码可维护性，是构建大型交互动效项目的最佳实践。

什么是ScrollTrigger

<header>
      <h1>案例 42：ScrollTrigger Pin 固定</h1>
      <p>滚动时固定元素并配合进度动画。</p>
    </header>
    <div class="spacer"></div>
    <section>
      <div class="panel">
        <div class="pin" id="pin">我被固定了</div>
      </div>
    </section>
    <section>
      <div class="panel">继续往下滚动</div>
    </section>
    <div class="spacer"></div>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/ScrollTrigger.min.js"></script>
    <script>
      // 注册 ScrollTrigger 插件
      gsap.registerPlugin(ScrollTrigger);

      // pin + scrub 绑定滚动进度
      gsap.to("#pin", {
        scale: 0.8,
        rotation: 10,
        scrollTrigger: {
          trigger: "#pin",
          start: "top center",
          end: "+=400",
          scrub: true,
          pin: true
        }
      });
    </script>

ScrollTrigger 是 GSAP（GreenSock Animation Platform） 中最强大、最受欢迎的插件之一，它能将滚动行为 （用户上下滑动页面）与GSAP 动画无缝结合，实现如"视差滚动"、"进度条动画"、"元素固定（Pin）"、"滚动触发动画"等高级交互动效。

---

📌 简单定义：

ScrollTrigger 让你把任何 GSAP 动画"绑定"到页面滚动位置上------当用户滚动到某个区域时，动画自动播放、暂停、反向或跟随滚动进度实时更新。

它本质上是一个滚动驱动的动画控制器。

---

✅ 核心能力：

1. 触发动画（Toggle）

• 当元素进入/离开视口时，播放/暂停动画。

scrollTrigger: {
  trigger: ".section",
  start: "top center", // 当 .section 顶部到达视口中心时触发
  toggleActions: "play none none reverse"
}

2. 滚动进度驱动（Scrub）

• 动画进度完全跟随滚动位置，形成"拖拽式"效果。

scrollTrigger: {
  scrub: true // 滚动多少，动画就播放到多少
}

3. 固定元素（Pin） ← 你的案例重点

• 在滚动过程中将元素"钉"在视口某处，直到滚动结束。

scrollTrigger: {
  pin: true,       // 固定 trigger 元素
  // 或 pin: "#otherElement" 固定其他元素
  end: "+=400"     // 固定持续 400px 的滚动距离
}

4. 标记与指示器（Markers）

• 开发时显示调试线（start/end 位置），方便调整。

scrollTrigger: {
  markers: true // 显示绿色（start）和红色（end）标记线
}

---

gsap.to("#pin", {
  scale: 0.8,
  rotation: 10,
  scrollTrigger: {
    trigger: "#pin",      // 监听 #pin 元素的滚动位置
    start: "top center",  // 当 #pin 顶部到达视口中心时开始
    end: "+=400",         // 滚动再往下 400px 后结束
    scrub: true,          // 动画进度随滚动平滑更新
    pin: true             // 在 start → end 区间内，#pin 被固定住
  }
});

用户体验流程：

1. 向下滚动，当 #pin 到达屏幕中央时 →
2. #pin 被固定在当前位置（不再随页面滚动而移动）；
3. 继续滚动的 400px 过程中，#pin 逐渐缩小并旋转 （scale: 0.8, rotation: 10）；
4. 滚动超过 400px 后，固定解除，#pin 随页面继续滚动。

💡 这就是"固定 + 进度动画"的经典组合，常用于产品展示、故事叙述等场景。

---

🌟 典型应用场景：

效果	描述
视差滚动	背景图慢速移动，前景快移
进度条/数字计数器	滚动时数字从 0 增长到目标值
元素入场/离场	卡片滑入、标题淡入
固定导航栏	滚动到某区域时导航栏吸顶
横向滚动画廊	垂直滚动驱动水平位移
3D 视差	滚动时多层元素产生景深感

---

⚙️ 关键配置项说明：

配置	作用
trigger	触发动画的参考元素（默认为动画目标）
start	动画开始的滚动位置（如 "top center"）
end	动画结束的滚动位置（如 "bottom bottom" 或 "+=500"）
scrub	true = 平滑跟随滚动；number = 延迟秒数
pin	true = 固定 trigger；"#id" = 固定指定元素
toggleActions	控制进入/离开时的播放行为（play pause resume reset）

📏 位置语法 ："edge1 edge2"

• edge1: trigger 元素的边缘（top/bottom/center）
• edge2: 视口的边缘（top/bottom/center）
  例如："top bottom" = trigger 顶部碰到视口底部时触发

---

⚠️ 注意事项：

• 必须注册插件：gsap.registerPlugin(ScrollTrigger)；
• pin 会自动包裹元素 并设置 position: sticky 或 fixed，无需手动写 CSS；
• 如果页面高度不足，可能看不到完整效果（需确保有足够滚动空间）；
• 免费功能 ：ScrollTrigger 是 GSAP 标准插件（无需 Club 会员）；
• 移动端性能优秀，支持触摸滚动。

---

📚 官方资源：

• 文档：greensock.com/docs/v3/Plu...
• 可视化工具：greensock.com/scroll-trig...

---

✅ 总结：

ScrollTrigger 是 GSAP 赋予网页"电影级滚动叙事能力"的核心插件------它将枯燥的滚动转化为精准、流畅、富有表现力的动画触发器，是现代高端网站交互动效的事实标准。

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>GSAP 案例 43 - ScrollTrigger toggleClass</title>
    <style>
      body {
        margin: 0;
        font-family: "Segoe UI", sans-serif;
        background: #0f172a;
        color: #e2e8f0;
      }
      header {
        padding: 80px 24px 40px;
        text-align: center;
      }
      section {
        min-height: 100vh;
        display: flex;
        align-items: center;
        justify-content: center;
      }
      .panel {
        width: 70%;
        max-width: 680px;
        padding: 32px;
        border-radius: 24px;
        background: #111827;
        box-shadow: 0 25px 60px rgba(15, 23, 42, 0.5);
        transition: transform 0.3s ease, background 0.3s ease;
      }
      .panel.active {
        transform: scale(1.03);
        background: #1f2937;
      }
      .spacer {
        height: 40vh;
      }
    </style>
  </head>
  <body>
    <header>
      <h1>案例 43：toggleClass 触发样式</h1>
      <p>滚动到卡片时添加高亮样式。</p>
    </header>
    <div class="spacer"></div>
    <section>
      <div class="panel" id="panel">滚动到这里会高亮</div>
    </section>
    <div class="spacer"></div>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/ScrollTrigger.min.js"></script>
    <script>
      // 注册 ScrollTrigger 插件
      gsap.registerPlugin(ScrollTrigger);

      ScrollTrigger.create({
        trigger: "#panel",
        start: "top 70%",
        end: "top 40%",
        toggleClass: "active"
      });
    </script>
  </body>
</html>

这段代码展示了 GSAP 的 ScrollTrigger 插件 中一个非常实用的功能：toggleClass。它的作用是------

当用户滚动到指定区域时，自动给目标元素添加或移除一个 CSS 类名，从而触发样式变化（如高亮、缩放、变色等），无需手动编写 JavaScript 逻辑。

---

🔍 逐行解析核心部分：

ScrollTrigger.create({
  trigger: "#panel",     // 监听 #panel 元素的滚动位置
  start: "top 70%",      // 当 #panel 的顶部进入视口 70% 位置时 → 添加类
  end: "top 40%",        // 当 #panel 的顶部到达视口 40% 位置时 → 移除类
  toggleClass: "active"  // 要切换的 CSS 类名
});

📏 滚动位置语法说明：

• "top 70%" 表示：trigger 元素的顶部 与 视口的 70% 高度线 对齐。
• 视口从上到下：0%（顶部）→ 100%（底部）
• 所以 70% 在视口偏下方，40% 在视口偏上方。

✅ 效果逻辑：

• 向下滚动，当 #panel 进入视口下部（70%） 时 → 添加 .active
• 继续滚动，当 #panel 上升到视口上部（40%） 时 → 移除 .active
• 向上滚动时行为相反（进入 end 区域加类，离开 start 区域去类）

---

🎨 CSS 配合实现高亮：

.panel {
  /* 默认样式 */
  background: #111827;
  transform: scale(1);
}

.panel.active {
  /* 滚动到区域时激活 */
  background: #1f2937;     /* 背景变亮 */
  transform: scale(1.03);  /* 轻微放大 */
}

通过 transition 实现了平滑过渡，视觉反馈更自然。

---

✅ toggleClass 的优势：

传统方式	使用 toggleClass
需监听 scroll 事件 + 计算位置 + 手动 classList.add/remove	✅ 一行配置自动完成
容易性能差（频繁触发 scroll）	✅ ScrollTrigger 内部优化（requestAnimationFrame + 节流）
逻辑分散，难维护	✅ 声明式写法，意图清晰

---

⚙️ 其他用法示例：

1. 切换多个类

toggleClass: "highlight zoom-in"

2. 作用于其他元素

ScrollTrigger.create({
  trigger: "#section",
  toggleClass: { targets: ".nav-item", className: "current" }
});

3. 配合 onToggle 回调

ScrollTrigger.create({
  trigger: "#panel",
  toggleClass: "active",
  onToggle: self => console.log("是否激活:", self.isActive)
});

---

⚠️ 注意事项：

• toggleClass 是 ScrollTrigger 的内置功能，无需额外插件；
• 类名切换是双向的：进入区间加类，离开区间去类；
• 如果 start 和 end 顺序颠倒（如 start: "top 40%", end: "top 70%"），则行为反转（常用于"离开时激活"）；
• 移动端兼容性良好，支持触摸滚动。

---

📚 官方文档：

👉 greensock.com/docs/v3/Plu...

---

✅ 总结：

ScrollTrigger.toggleClass 是实现"滚动高亮"、"区域激活"等交互的最简洁方案------它将复杂的滚动监听与 DOM 操作封装成声明式配置，让你专注于 CSS 样式设计，大幅提升开发效率与代码可读性。

getProperty + getVelocity 是什么

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>GSAP 案例 44 - velocity / getProperty</title>
    <style>
      body {
        margin: 0;
        min-height: 100vh;
        display: flex;
        align-items: center;
        justify-content: center;
        font-family: "Segoe UI", sans-serif;
        background: #0f172a;
        color: #e2e8f0;
      }
      .card {
        width: 620px;
        padding: 28px;
        border-radius: 20px;
        background: #111827;
        box-shadow: 0 20px 50px rgba(15, 23, 42, 0.5);
      }
      .track {
        height: 100px;
        border-radius: 14px;
        background: #0b1220;
        position: relative;
        margin: 18px 0;
      }
      .dot {
        width: 32px;
        height: 32px;
        border-radius: 50%;
        background: #a3e635;
        position: absolute;
        top: 34px;
        left: 20px;
      }
      .info {
        font-size: 14px;
        color: #94a3b8;
      }
      button {
        width: 100%;
        margin-top: 12px;
        padding: 12px 16px;
        border: none;
        border-radius: 12px;
        font-size: 14px;
        cursor: pointer;
        background: #a3e635;
        color: #0f172a;
        font-weight: 600;
      }
    </style>
  </head>
  <body>
    <div class="card">
      <h1>案例 44：getProperty + getVelocity</h1>
      <p>读取属性与速度，了解当前运动状态。</p>
      <div class="track">
        <div class="dot" id="dot"></div>
      </div>
      <div class="info" id="info">x: 0 | velocity: 0</div>
      <button id="play">播放</button>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
    <script>
      const dot = document.querySelector("#dot");
      const info = document.querySelector("#info");
      const playButton = document.querySelector("#play");

      const tween = gsap.to(dot, {
        x: 480,
        duration: 2,
        ease: "power1.inOut",
        paused: true,
        onUpdate: () => {
          const x = Math.round(gsap.getProperty(dot, "x"));
          const velocity = Math.round(tween.getVelocity());
          info.textContent = `x: ${x} | velocity: ${velocity}`;
        }
      });

      playButton.addEventListener("click", () => {
        tween.restart();
      });
    </script>
  </body>
</html>

在 GSAP（GreenSock Animation Platform） 中，gsap.getProperty() 和 tween.getVelocity() 是两个用于实时读取动画状态的实用工具方法，常用于调试、交互反馈或基于物理状态的逻辑判断。

---

✅ 一、gsap.getProperty(target, property, unit?)

🔍 作用：

获取目标元素当前被 GSAP 控制的某个 CSS 属性或 transform 值。

即使该属性是通过 transform（如 x, y, rotation）设置的，也能正确返回数值。

📌 语法：

gsap.getProperty(element, "propertyName", "unit?");

• element：DOM 元素
• "propertyName"：属性名，如 "x", "opacity", "backgroundColor"
• "unit?"（可选）：指定返回单位，如 "px", "deg"；默认返回纯数字

const x = Math.round(gsap.getProperty(dot, "x"));

• 实时读取小球当前的 水平位移 x 值（以像素为单位的数字）
• 即使你用 gsap.to(dot, { x: 480 }) 设置的是"相对位移"，getProperty 也能返回绝对计算值

⚠️ 注意：它读取的是 GSAP 内部记录的值 ，不是 getComputedStyle() 的结果，因此更准确、更高效（尤其对 transform 属性）。

---

✅ 二、tween.getVelocity()

🔍 作用：

获取当前动画目标属性的瞬时速度（单位/秒）。

对于多属性动画（如同时动 x 和 y），默认返回第一个属性的速度；也可指定属性：

tween.getVelocity("x") // 获取 x 方向速度

📌 特点：

• 速度单位：每秒变化量 （如 px/s, deg/s）
• 方向有正负：+ 表示正向（如向右），- 表示反向（如向左）
• 在 onUpdate 回调中调用最准确

const velocity = Math.round(tween.getVelocity());

• 返回小球在 x 方向上的当前速度（px/s）
• 动画开始和结束时速度接近 0（因为使用了 power1.inOut 缓动）
• 中间时刻速度最大（约 ±240 px/s）

---

🔬 动画过程中的典型值（duration: 2s, x: 0 → 480）：

时间	x 值	velocity (px/s)	说明
0s	0	0	起始，静止
0.5s	~120	~240	加速到峰值
1.0s	240	0	中点，瞬时静止（inOut 对称）
1.5s	~360	~-240	反向加速（减速阶段）
2.0s	480	0	结束，静止

📌 注意：power1.inOut 是先加速后减速，在中点速度为 0（这是缓动函数决定的）。

---

🌟 典型应用场景：

场景	用途
物理模拟	根据速度决定反弹强度、摩擦力
交互反馈	鼠标松开时根据拖拽速度继续滑动（惯性滚动）
游戏开发	判断角色是否在移动、碰撞检测
动画调试	实时监控属性与速度变化
动态效果	速度越大，粒子越多 / 模糊越强

---

⚠️ 注意事项：

• getProperty 仅能读取 GSAP 已经控制过的属性；
• getVelocity() 必须在 动画进行中 调用才有意义（暂停/结束后返回 0）；
• 对于 Timeline，需在具体 tween 上调用 getVelocity()；
• 这两个方法都是 GSAP 核心 API，无需额外插件。

---

📚 官方文档：

• getProperty: greensock.com/docs/v3/GSA...
• getVelocity: greensock.com/docs/v3/GSA...

---

✅ 总结：

gsap.getProperty() 和 tween.getVelocity() 是 GSAP 提供的"动画状态探测器"------它们让你能精确掌握元素当前的位置和运动速度，为构建基于物理、交互或调试需求的高级动画提供了关键数据支持。

什么是utils.random / wrap / interpolate

<!DOCTYPE html>
<html lang="zh-CN">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>GSAP 案例 45 - utils random/wrap/interpolate</title>
  <style>
    body {
      margin: 0;
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      font-family: "Segoe UI", sans-serif;
      background: #0b1020;
      color: #e2e8f0;
    }

    .card {
      width: 640px;
      padding: 28px;
      border-radius: 20px;
      background: #111827;
      box-shadow: 0 20px 50px rgba(15, 23, 42, 0.5);
    }

    .stage {
      height: 160px;
      border-radius: 16px;
      background: #0f172a;
      position: relative;
      overflow: hidden;
      margin: 18px 0;
    }

    .dot {
      width: 30px;
      height: 30px;
      border-radius: 50%;
      background: #38bdf8;
      position: absolute;
      top: 65px;
      left: 20px;
    }

    button {
      width: 100%;
      padding: 12px 16px;
      border: none;
      border-radius: 12px;
      font-size: 14px;
      cursor: pointer;
      background: #38bdf8;
      color: #0f172a;
      font-weight: 600;
    }

    .info {
      margin-top: 8px;
      font-size: 13px;
      color: #94a3b8;
    }
  </style>
</head>

<body>
  <div class="card">
    <h1>案例 45：utils.random / wrap / interpolate</h1>
    <p>快速生成随机值、循环值与插值。</p>
    <div class="stage">
      <div class="dot" id="dot"></div>
    </div>
    <button id="play">随机移动</button>
    <div class="info" id="info"></div>
  </div>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
  <script>
    const dot = document.querySelector("#dot");
    const info = document.querySelector("#info");
    const playButton = document.querySelector("#play");

    // random 生成随机数，wrap 限制循环范围，interpolate 计算插值
    const randomX = gsap.utils.random(40, 540, 1);
    const wrapHue = gsap.utils.wrap(0, 360);
    const mix = gsap.utils.interpolate(0, 1);

    let step = 0;

    playButton.addEventListener("click", () => {
      const x = randomX;
      const hue = wrapHue(step * 80);
      const scale = mix(0.7, 1.4);

      gsap.to(dot, {
        x,
        scale,
        backgroundColor: `hsl(${hue}, 90%, 60%)`,
        duration: 0.6,
        ease: "power2.out"
      });

      info.textContent = `x: ${x}px | hue: ${hue} | scale: ${scale.toFixed(2)}`;
      step += 1;
    });
  </script>
</body>

</html>

在 GSAP（GreenSock Animation Platform） 中，gsap.utils 是一个内置的实用工具函数集合，提供了许多高效、简洁的辅助方法，用于处理动画中常见的数学和逻辑操作。

你提到的三个方法：

• gsap.utils.random
• gsap.utils.wrap
• gsap.utils.interpolate

是其中最常用、最强大的三个工具，分别用于生成随机值 、循环限制范围 和计算插值。它们让复杂逻辑变得简单，且性能优异。

---

✅ 1. gsap.utils.random(min, max, [step])

🔍 作用：

生成一个指定范围内的随机数（可选步长）。

📌 语法：

const rand = gsap.utils.random(min, max, step);

• min：最小值
• max：最大值
• step（可选）：步长（如 1 表示整数，0.1 表示保留一位小数）

⚠️ 注意：它返回的是一个函数！调用该函数才会生成新随机数。

但如果你直接传数字（如你的代码），GSAP 会自动缓存一次结果（等价于 random(40, 540, 1)()）。

const randomX = gsap.utils.random(40, 540, 1); // 实际返回一个数字（因为未作为函数调用）

• 每次点击按钮，x 都是一个 40~540 之间的整数
• 用于让小球随机水平移动

✅ 更推荐写法（每次点击都新随机）：

playButton.addEventListener("click", () => {
  const x = gsap.utils.random(40, 540, 1)(); // 加 () 才是函数调用
});

---

✅ 2. gsap.utils.wrap(min, max)

🔍 作用：

将任意数值"包裹"到 [min, max) 范围内，实现无缝循环（类似取模 %，但支持浮点数和负数）。

📌 语法：

const wrap = gsap.utils.wrap(min, max);
const result = wrap(value); // 返回循环后的值

🌰 例子：

const wrap360 = gsap.utils.wrap(0, 360);
wrap360(400)   // → 40   （400 - 360）
wrap360(-20)   // → 340  （-20 + 360）
wrap360(720)   // → 0    （720 % 360）

const hue = wrapHue(step * 80); // step=0→0, step=1→80, step=2→160, step=3→240, step=4→320, step=5→40→40...

• 实现 HSL 色相（0~360）的循环切换，避免颜色溢出
• 视觉上形成：蓝 → 紫 → 红 → 橙 → 黄 → 绿 → 蓝 ... 的循环

---

✅ 3. gsap.utils.interpolate(start, end)

🔍 作用：

创建一个插值函数，根据进度值（0~1）计算 start 到 end 之间的中间值。

📌 语法：

const interpolator = gsap.utils.interpolate(start, end);
const value = interpolator(progress); // progress ∈ [0, 1]

🌰 例子：

const mix = gsap.utils.interpolate(10, 50);
mix(0)   // → 10
mix(0.5) // → 30
mix(1)   // → 50

它不仅支持数字，还支持颜色、数组、甚至对象！

const scale = mix(0.7, 1.4); // ❌ 这里有误！

正确用法应该是：

// 先创建插值函数
const scaleInterp = gsap.utils.interpolate(0.7, 1.4);

// 再用 0~1 之间的值去插值（比如用 Math.random()）
const scale = scaleInterp(Math.random());

这会导致 scale = 0.7（因为 mix(0.7) ≈ 0.7，第二个参数被忽略）。

✅ 修复建议：

// 方案 1：直接随机 scale
const scale = gsap.utils.random(0.7, 1.4, 0.01)();

// 方案 2：用插值 + 随机进度
const getScale = gsap.utils.interpolate(0.7, 1.4);
const scale = getScale(Math.random());

---

🌟 总结对比：

工具	用途	返回值	典型场景
random(min, max, step)	生成随机数	函数（或直接数值）	随机位置、延迟、颜色
wrap(min, max)	循环限制数值	函数	色相循环、角度归一化、无限滚动
interpolate(a, b)	计算 a→b 的中间值	函数	动态缩放、颜色混合、进度映射

---

🎯 高级技巧（Bonus）：

支持颜色插值：

const colorMix = gsap.utils.interpolate("red", "blue");
colorMix(0.5); // → "rgb(128, 0, 128)"（紫色）

数组插值：

const pointMix = gsap.utils.interpolate([0, 0], [100, 200]);
pointMix(0.5); // → [50, 100]

---

📚 官方文档：

👉 greensock.com/docs/v3/GSA...

---

✅ 最终总结：

gsap.utils.random、wrap 和 interpolate 是 GSAP 提供的"动画数学工具箱"------它们以极简 API 解决了随机性、循环性和连续性三大常见需求，让你无需手写复杂公式，即可构建丰富、动态、可控的交互动效。

什么是timeScale / yoyoEase

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>GSAP 案例 46 - timeScale / yoyoEase</title>
    <style>
      body {
        margin: 0;
        min-height: 100vh;
        display: flex;
        align-items: center;
        justify-content: center;
        font-family: "Segoe UI", sans-serif;
        background: #0f172a;
        color: #e2e8f0;
      }
      .card {
        width: 620px;
        padding: 28px;
        border-radius: 20px;
        background: #111827;
        box-shadow: 0 20px 50px rgba(15, 23, 42, 0.5);
      }
      .track {
        height: 90px;
        border-radius: 14px;
        background: #0b1220;
        position: relative;
        margin: 18px 0;
      }
      .ball {
        width: 46px;
        height: 46px;
        border-radius: 50%;
        background: #f472b6;
        position: absolute;
        top: 22px;
        left: 20px;
      }
      .controls {
        display: grid;
        grid-template-columns: repeat(3, 1fr);
        gap: 10px;
      }
      button {
        padding: 10px 12px;
        border: none;
        border-radius: 12px;
        font-size: 13px;
        cursor: pointer;
        background: #1f2937;
        color: #e5e7eb;
      }
      button.primary {
        background: #f472b6;
        color: #0f172a;
        font-weight: 600;
      }
    </style>
  </head>
  <body>
    <div class="card">
      <h1>案例 46：timeScale 与 yoyoEase</h1>
      <p>调整播放速度，并在往返时使用不同缓动。</p>
      <div class="track">
        <div class="ball" id="ball"></div>
      </div>
      <div class="controls">
        <button id="slow">慢速</button>
        <button class="primary" id="play">播放</button>
        <button id="fast">快速</button>
      </div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.1/dist/gsap.min.js"></script>
    <script>
      const ball = document.querySelector("#ball");
      const playButton = document.querySelector("#play");
      const slowButton = document.querySelector("#slow");
      const fastButton = document.querySelector("#fast");

      // yoyoEase 可以在回放时使用不同缓动
      const tween = gsap.to(ball, {
        x: 520,
        duration: 1.6,
        ease: "power2.out",
        yoyo: true,
        repeat: -1,
        yoyoEase: "power2.in",
        paused: true
      });

      playButton.addEventListener("click", () => {
        tween.paused(!tween.paused());
      });

      slowButton.addEventListener("click", () => {
        tween.timeScale(0.6);
      });

      fastButton.addEventListener("click", () => {
        tween.timeScale(1.6);
      });
    </script>
  </body>
</html>

在 GSAP（GreenSock Animation Platform） 中，timeScale 和 yoyoEase 是两个用于精细控制动画播放行为的强大特性：

---

✅ 一、timeScale：控制动画播放速度

🔍 作用：

调整动画的时间流速，实现快放、慢放、甚至倒放，而不改变 duration。

📌 基本用法：

tween.timeScale(1);   // 正常速度（默认）
tween.timeScale(0.5); // 半速（慢动作）
tween.timeScale(2);   // 2倍速（快进）
tween.timeScale(-1);  // 反向播放（倒放）

• timeScale 是一个乘数因子 ：
  • 1 = 100% 速度
  • 0.6 = 60% 速度（变慢）
  • 1.6 = 160% 速度（变快）

slowButton.addEventListener("click", () => {
  tween.timeScale(0.6); // 慢速
});

fastButton.addEventListener("click", () => {
  tween.timeScale(1.6); // 快速
});

• 点击按钮即可实时改变动画速度，无需重新创建动画；
• 即使动画正在播放，也能无缝变速。

⚠️ 注意：timeScale 不影响 duration 的设定值，只影响实际播放耗时。

---

✅ 二、yoyoEase：为往返动画（yoyo）指定不同的缓动函数

🔍 背景知识：什么是 yoyo？

• 当设置 repeat: -1（无限重复） + yoyo: true 时，
• 动画会正向播放 → 反向播放 → 正向播放 → ...，形成"来回"效果。

📌 默认问题：

• 如果只设 ease: "power2.out"，
• 那么正向和反向都使用同一个缓动 ，导致：
  • 正向：先快后慢（out）
  • 反向：先慢后快（因为是倒放 out）

但很多时候，我们希望去程和回程有不同的运动感觉！

✅ 解决方案：yoyoEase

yoyoEase 允许你为"回程"（反向播放）单独指定一个缓动函数。

💡 在你的代码中：

const tween = gsap.to(ball, {
  x: 520,
  duration: 1.6,
  ease: "power2.out",      // 去程：先快后慢（弹出感）
  yoyo: true,
  repeat: -1,
  yoyoEase: "power2.in",   // 回程：先慢后快（吸入感）
  paused: true
});

🎯 视觉效果对比：

阶段	缓动	运动特点
去程（→）	power2.out	快速冲出去，然后缓缓停下
回程（←）	power2.in	缓缓启动，然后快速收回

这比单纯用 yoyo: true + 单一缓动更自然、更有"弹性"！

---

🔬 技术细节补充：

1. yoyoEase 的工作原理：

• GSAP 不会倒放 ease ，而是正向播放 yoyoEase 来模拟回程。
• 所以 ease: "out" + yoyoEase: "in" = 去程快停 + 回程快启，非常合理。

2. yoyoEase 支持所有缓动类型：

yoyoEase: "elastic.out"
yoyoEase: "bounce.inOut"
yoyoEase: CustomEase.create(...)

3. timeScale 是可叠加的：

tween.timeScale(2).timeScale(0.5); // 最终 = 1（2 * 0.5）

---

🌟 典型应用场景：

场景	用途
UI 微交互动效	按钮点击"弹跳"：去程快，回程缓
游戏对象移动	敌人巡逻：匀速去，加速回
视频/音频播放器	拖拽预览时慢放，正常播放时快放
科学可视化	模拟不同速度下的物理过程

---

⚠️ 注意事项：

• yoyoEase 仅在 yoyo: true 时生效；
• timeScale 影响整个时间线或 tween，包括子动画；
• 两者都是 GSAP 核心功能，无需额外插件；
• timeScale(0) 会暂停动画（等价于 paused(true)）。

---

📚 官方文档：

• timeScale: greensock.com/docs/v3/GSA...
• yoyoEase: greensock.com/docs/v3/GSA...

---

✅ 总结：

timeScale 让你像"调速旋钮"一样控制动画节奏，而 yoyoEase 则赋予往返动画"去程与回程不同性格"的能力------两者结合，可构建出既灵活又富有表现力的交互动效，是 GSAP 高级动画控制的标志性特性。