GSAP 动画中需要数值映射、随机吸附…

编写或审查 GSAP 动画代码时，用 gsap.utils 提供的纯辅助函数处理数学、数组/集合、单位解析和值映射。

适用场景

解决思路

1. 使用 gsap.utils 下的纯辅助函数，无需注册；可在 tween vars、ScrollTrigger/Observer 回调或任何驱动 GSAP 的 JS 中调用，形式如 gsap.utils.clamp()。
2. 多数工具把待转换的值作为最后一个参数；省略该参数时，工具返回一个函数，之后再用值调用它；当同一范围/配置要多次 clamp、map、normalize 或 snap 时，用这种函数形式（例如 mousemove 处理器或 tween 回调）。
3. 例外：random() 不要省略值来获取可复用函数；应在最后传入 true 作为 returnFunction。
4. clamp(min, max, value?)：把 value 限制在 min 到 max 之间；省略 value 时得到 clamp(min, max)(value) 函数。
5. mapRange(inMin, inMax, outMin, outMax, value?)：把值从一个范围映射到另一个范围；用于把滚动位置、progress(0–1) 或输入范围转换成动画范围；省略 value 时得到 mapRange(inMin, inMax, outMin, outMax)(value) 函数。
6. normalize(min, max, value?)：把给定范围内的值归一化到 0–1；当目标范围是 0–1 时，它是 map 的逆操作；省略 value 时得到 normalize(min, max)(value) 函数。
7. interpolate(start, end, progress?)：按 progress(0–1) 在 start 和 end 之间插值；支持数字、颜色和键名匹配的对象；省略 progress 时得到 interpolate(start, end)(progress) 函数。
8. random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])：返回 minimum–maximum 范围内的随机数，或从数组随机取一个元素；可选 snapIncrement 把结果吸附到最近倍数（如 5 → 5 的倍数）；要得到可复用函数，在最后传 true，返回的函数无参数且每次返回新的随机值；这是唯一用 true 而不是省略值来生成函数形式的工具。
9. 在 tween vars 中用字符串形式 "random(-100, 100)"、"random(-100, 100, 5)" 或 "random([0, 100, 200])"；GSAP 会按每个目标求值，例如 gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 }) 和 gsap.to(".item", { backgroundColor: "random([red, blue, green])" })。
10. snap(snapTo, value?)：把值吸附到 snapTo 的最近倍数，或吸附到允许值数组中的最近值；省略 value 时得到 snap(snapTo)(value) 或 snap(snapArray)(value) 函数。
11. 在 tween 中用 snap 做网格或步进动画，例如 gsap.to(".x", { x: 200, snap: { x: 20 } })。
12. shuffle(array)：返回一个包含相同元素但随机排序的新数组；用于随机化顺序，例如配合 stagger 的 "random" 使用副本。
13. distribute(config)：返回一个函数，根据目标在数组（或网格）中的位置给每个目标分配值；用于高级 stagger，以及需要在许多元素间铺开 scale、opacity、x、delay 等值时。
14. distribute 返回的函数接收 (index, target, targets)；可以手动调用，也可以直接把结果传入 tween，GSAP 会按每个目标用 index、element 和数组调用它。
15. distribute 的 config（均可选）：base 为起始值，默认 0；amount 为要在所有目标间分配的总量（加到 base 上），例如 100 个目标 amount: 1 → 每个间隔 0.01，若要固定每目标步长则用 each；each 为每个目标之间增加的量（加到 base 上），例如 4 个目标 each: 1 → 0,1,2,3，若要拆分总量则用 amount；from 为分配起点：索引，或 "start"、"center"、"edges"、"random"、"end"，或如 [0.25, 0.75] 的比例，默认 0；grid 为用网格位置代替扁平索引：[rows, columns]（如 [5, 10]）或 "auto" 自动检测，省略则为扁平数组；axis 为在网格中限制到单轴（"x" 或 "y"）；ease 为沿缓动曲线分配值（如 "power1.inOut"），默认 "none"。
16. 在 tween 中把 distribute(config) 的结果作为属性值传入，GSAP 会对每个目标调用该函数，参数为 (index, target, targets)；例如 scale 中间元素 0.5、外边缘 3：gsap.to(".class", { scale: gsap.utils.distribute({ base: 0.5, amount: 2.5, from: "center" }) })。
17. 手动使用 distribute 时，用 (index, target, targets) 调用返回的函数来获取该索引对应的值；例如 const distributor = gsap.utils.distribute({ base: 50, amount: 100, from: "center", ease: "power1.inOut" }); const targets = gsap.utils.toArray(".box"); const valueForIndex2 = distributor(2, targets[2], targets);。
18. getUnit(value)：返回值的单位字符串（如 "px"、"%"、"deg"）；用于归一化或转换值时。
19. unitize(value, unit)：给数字追加单位，或如果值已有单位则原样返回；用于构建 CSS 值或 tween 结束值。
20. splitColor(color, returnHSL?)：把颜色字符串转换为数组 [red, green, blue]（0–255），或 [red, green, blue, alpha]（存在/需要 alpha 时为 4 个元素）；第二参数传 true 得到 [hue, saturation, lightness] 或 [hue, saturation, lightness, alpha]（HSL/HSLA）；支持 "rgb()"、"rgba()"、"hsl()"、"hsla()"、hex 和命名颜色（如 "red"）；用于动画化颜色分量或构建渐变。
21. selector(scope)：返回一个作用域选择器函数，只在给定元素（或 ref）内查找元素；用于组件中让 ".box" 等选择器只匹配该组件后代，而不是整个文档；接受 DOM 元素或 ref（如 React ref；会处理 .current）。
22. toArray(value, scope?)：把值转换为数组，包括选择器字符串（可限定在 scope 元素内）、NodeList、HTMLCollection、单个元素或数组；当要把混合输入传给 GSAP（如 targets）且需要真正的数组时使用。
23. pipe(...functions)：组合函数：pipe(f1, f2, f3)(value) 返回 f3(f2(f1(value)))；用于在 tween 或回调中应用一串转换（如 normalize → mapRange → snap）。
24. wrap(min, max, value?)：把值环绕到 min–max 范围（包含 min，不包含 max）；用于无限滚动或循环值；省略 value 时得到 wrap(min, max)(value) 函数。
25. wrapYoyo(min, max, value?)：把值环绕到范围内并在端点反弹（yoyo）；用于在范围内来回移动；省略 value 时得到 wrapYoyo(min, max)(value) 函数。
26. 最佳实践：当同一范围/配置会多次使用时，省略 value 参数得到可复用函数，例如 let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress)。
27. 最佳实践：网格对齐或步进值用 snap；当 GSAP 或代码需要从选择器或 NodeList 得到真正数组时用 toArray。
28. 最佳实践：在组件中使用 gsap.utils.selector(scope)，让选择器限定到容器或 ref。
29. 不要假设 mapRange / normalize 会处理单位；它们只处理数字；当单位重要时使用 getUnit / unitize。
30. 不要覆盖或依赖未文档化的行为；坚持使用文档化 API。
31. 构建动画时，将本技能与 gsap-core、gsap-timeline 和 gsap-scrolltrigger 一起使用；CustomEase 和其他 easing 工具属于 gsap-plugins。

适用边界 · 注意事项

• 需要处理带单位的值（如 px、%、deg）时，不要用 mapRange/normalize，它们只处理数字；应改用 getUnit/unitize。
• 不要覆盖或依赖未文档化的 gsap.utils 行为，只使用文档化 API。
• 若项目未引入 GSAP，无法使用这些 gsap.utils 辅助函数。