gsap-utils 是 GSAP 官方提供的技能,专注 gsap.utils 这一组纯辅助函数。它不需要注册,所有函数都挂在 gsap.utils 上调用,可用于 tween 变量(如基于函数的值)、ScrollTrigger 或 Observer 回调,以及任何驱动 GSAP 的 JavaScript 代码中。
主要能力可分为几类:
一、夹取与范围。clamp(min, max, value?) 把数值限制在最小与最大之间;mapRange(inMin, inMax, outMin, outMax, value?) 把一个范围映射到另一个范围;normalize(min, max, value?) 把值归一化到 0–1;interpolate(start, end, progress?) 在两个值之间按 0–1 的进度插值,支持数字、颜色和键名对应的对象。
二、随机与吸附。random() 返回区间内的随机数或数组中的随机元素,可传入 snapIncrement 吸附到最近倍数;snap(snapTo, value?) 把值吸附到最近倍数或数组中最接近的允许值;shuffle(array) 返回元素顺序随机的新数组;distribute(config) 返回按目标在数组或网格中的位置分配值的函数,支持 base、amount、each、from、grid、axis、ease 等配置,常用于高级交错动画。
三、单位与解析。getUnit(value) 返回值的单位字符串;unitize(value, unit) 给数字追加单位,已有单位则原样返回;splitColor(color, returnHSL?) 把颜色字符串拆成 RGB(A) 或 HSL(A) 数组。
四、数组与集合。selector(scope) 返回限定在给定元素或 ref 内的选择器函数;toArray(value, scope?) 把选择器字符串、NodeList、HTMLCollection、单个元素或数组转换为真正的数组;pipe(...functions) 组合多个函数,按顺序串联执行。
五、循环取值。wrap(min, max, value?) 把值包裹进区间实现循环;wrapYoyo(min, max, value?) 在区间两端反弹。
使用方式上,多数工具函数把要转换的值作为最后一个参数;省略该参数会返回一个稍后接收值的函数,适合在 mousemove 处理器或 tween 回调中复用同一配置。random() 是例外:需要传入 true 作为最后一个参数才返回可复用函数。random 还支持 tween 变量中的字符串写法,如 "random(-100, 100, 5)"。
适用场景包括:把滚动位置或进度映射为动画数值、随机化、吸附到网格、归一化输入、在组件内做作用域选择、以及把多个变换串联成管道。
限制与注意:mapRange 和 normalize 只处理数字,不处理单位,涉及单位时需配合 getUnit 与 unitize;应只使用文档中记录的 API,不要依赖未记录行为。文档中还建议在相同配置多次使用时省略 value 参数以获得可复用函数,需要真实数组时使用 toArray。
该技能可与 gsap-core、gsap-timeline、gsap-scrolltrigger 配合构建动画;CustomEase 及其他缓动工具位于 gsap-plugins。更多说明见 https://gsap.com/docs/v3/HelperFunctions。