gsap.utils 提供一组纯辅助函数（pure helpers），无需注册即可使用。它们可以写在 tween 参数中（如基于函数的值），用于 ScrollTrigger 或 Observer 回调，或任何驱动 GSAP 的 JavaScript 代码。所有函数都挂在 gsap.utils 上（例如 gsap.utils.clamp()）。
一、何时使用 当编写或审查使用 gsap.utils 进行数学计算、数组/集合处理、单位解析或动画数值映射的代码时适用（例如把滚动映射为某个值、随机化、吸附到网格、归一化输入等）。相关技能：构建动画时配合 gsap-core、gsap-timeline 和 gsap-scrolltrigger 使用；CustomEase 及其他缓动工具位于 gsap-plugins。
二、省略值参数的函数形式 很多工具把要转换的值作为最后一个参数。如果省略该参数，工具会返回一个函数，之后再用该值调用它。当你需要用同一套配置对多个值进行 clamp、map、normalize 或 snap 时（例如在 mousemove 处理器或 tween 回调中），使用这种函数形式。例外是 random()：需把 true 作为最后一个参数来获得可复用函数（不要省略值）。例如：gsap.utils.clamp(0, 100, 150) 返回 100；而 let c = gsap.utils.clamp(0, 100); c(150) 返回 100，c(-10) 返回 0。
三、范围与夹取 clamp(min, max, value?) 将值限制在 min 与 max 之间，省略 value 得到 clamp(min, max)(value)。 mapRange(inMin, inMax, outMin, outMax, value?) 把一个值从一个范围映射到另一个范围，用于把滚动位置、进度（0–1）或输入范围转换为动画范围，省略 value 得到 mapRange(...)(value)。 normalize(min, max, value?) 返回对给定范围归一化到 0–1 的值，是目标范围为 0–1 时映射的逆运算，省略 value 得到 normalize(min, max)(value)。 interpolate(start, end, progress?) 在给定进度（0–1）下在两个值之间插值，可处理数字、颜色以及键匹配的对象，省略 progress 得到 interpolate(start, end)(progress)。
四、随机与吸附 random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction]) 返回范围内随机数，或从数组中随机取一个元素。可选的 snapIncrement 会把结果吸附到最近的倍数（如 5 表示 5 的倍数）。要获得可复用函数，把 true 作为最后一个参数传入（returnFunction），返回的函数不带参数且每次返回新的随机值。这是唯一用 true（而非省略值）表示函数形式的工具。在 tween 参数中也可使用字符串形式 "random(-100, 100)"、"random(-100, 100, 5)" 或 "random([0, 100, 200])"，GSAP 会按每个目标求值。 snap(snapTo, value?) 把值吸附到 snapTo 的最近倍数，或吸附到允许值数组中最接近的值，省略 value 得到 snap(snapTo)(value)。可在 tween 中用于网格或按步动画，如 gsap.to(".x", { x: 200, snap: { x: 20 } })。 shuffle(array) 返回元素相同但顺序随机的新数组。 distribute(config) 返回一个函数，根据目标在数组（或网格）中的位置为其分配值。用于高级 stagger。返回的函数接收 (index, target, targets)。配置项（均可选）包括：base（起始值，默认 0）、amount（在所有目标间分配的总量，加到 base）、each（每个目标之间增加的固定量，加到 base）、from（起始位置：索引，或 "start"、"center"、"edges"、"random"、"end"，或比例数组如 [0.25, 0.75]，默认 0）、grid（用网格位置代替扁平索引：[rows, columns] 或 "auto" 自动检测）、axis（在网格中限定某一轴："x" 或 "y"）、ease（沿缓动曲线分配值，默认 "none"）。在 tween 中把 distribute(config) 的结果作为属性值即可，GSAP 会为每个目标调用它。
五、单位与解析 getUnit(value) 返回值单位字符串（如 "px"、"%"、"deg"）。 unitize(value, unit) 给数字追加单位，若值已有单位则原样返回。 splitColor(color, returnHSL?) 将颜色字符串转换为数组：[red, green, blue]（0–255），或存在/需要 alpha 时为四元素的 [red, green, blue, alpha]。第二个参数传 true 则返回 [hue, saturation, lightness] 或 [hue, saturation, lightness, alpha]。支持 "rgb()"、"rgba()"、"hsl()"、"hsla()"、十六进制和颜色名（如 "red"）。
六、数组与集合 selector(scope) 返回作用域选择器函数，只在给定元素（或 ref）内查找元素，接受 DOM 元素或 ref（如 React ref，会处理 .current）。 toArray(value, scope?) 把值转换为数组：选择器字符串（作用于 scope）、NodeList、HTMLCollection、单个元素或数组。 pipe(...functions) 组合函数：pipe(f1, f2, f3)(value) 返回 f3(f2(f1(value)))，用于在 tween 或回调中串联变换链（如 normalize → mapRange → snap）。 wrap(min, max, value?) 把值环绕进 min–max 范围（含 min，不含 max），用于无限滚动或循环值，省略 value 得到 wrap(min, max)(value)。 wrapYoyo(min, max, value?) 在范围内环绕值，并在两端反弹（yoyo），省略 value 得到 wrapYoyo(min, max)(value)。
七、最佳实践 当同一范围/配置多次使用时（如滚动处理器、tween 回调），省略 value 参数以获得可复用函数。用 snap 处理网格对齐或按步的值；当 GSAP 或代码需要从选择器或 NodeList 得到真正的数组时使用 toArray。在组件中使用 gsap.utils.selector(scope) 让选择器限定在容器或 ref 内。 不要假设 mapRange / normalize 处理单位，它们只处理数字，涉及单位时使用 getUnit / unitize。不要覆盖或依赖未文档化的行为，请坚持使用已文档化的 API。 更多信息见 https://gsap.com/docs/v3/HelperFunctions。