SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场gsap-utils

gsap-utils

设计与创作

查看项目

更新于 10-24 16:21

技能介绍

用途

gsap.utils 是 GSAP 的官方工具函数集合，提供纯函数式辅助方法，无需 register 即可直接通过 gsap.utils 调用。它主要服务于动画相关代码中的数值计算、输入映射、数组与选择器处理、单位解析，以及按目标元素分配数值。资料指出，可在 tween 的属性变量（如函数式取值）、ScrollTrigger 或 Observer 回调，以及任何驱动 GSAP 的 JavaScript 中使用。

主要能力

限制、范围与插值

  • clamp(min, max, value?)：将数值限制在 min 与 max 之间。省略 value 时返回函数，用法为 clamp(min, max)(value)。
  • mapRange(inMin, inMax, outMin, outMax, value?)：把数值从一个区间映射到另一个区间，适合将滚动位置、进度（0–1）或输入范围转换为动画范围。省略 value 时返回可复用函数。
  • normalize(min, max, value?)：将数值归一化为给定区间下的 0–1。省略 value 时返回可复用函数。
  • interpolate(start, end, progress?)：在给定进度（0–1）下于两个值之间插值，支持数字、颜色和键相同的对象。省略 progress 时返回可复用函数。

随机与吸附

  • random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])：返回区间内的随机数，或从数组中随机取一个元素，可选按步长吸附。要得到可复用函数需在最后传 true；这是唯一用 true 而非省略 value 来表示函数形式的工具。还支持在 tween 变量中用字符串形式如 "random(-100, 100, 5)"，由 GSAP 按目标求值。
  • snap(snapTo, value?)：将数值吸附到 snapTo 的最近倍数，或吸附到允许值数组中的最近值。省略 value 时返回函数。可在 tween 中用于网格或按步长动画，如 snap: { x: 20 }。
  • shuffle(array)：返回元素顺序随机化的新数组。
  • distribute(config)：返回一个函数，根据目标在数组或网格中的位置为其分配数值，常用于高级 stagger。配置可选，包括 base、amount、each、from、grid、axis、ease。返回的函数接收 (index, target, targets)，既可手动调用，也可直接作为 tween 的属性值交给 GSAP 逐目标调用。

单位与解析

  • getUnit(value)：返回值的单位字符串，如 "px"、"%"、"deg"，无单位时返回空字符串。
  • unitize(value, unit)：给数字追加单位，若已有单位则原样返回。
  • splitColor(color, returnHSL?)：把颜色字符串转为数组。默认返回 RGB 或 RGBA 分量；第二个参数传 true 时返回 HSL 或 HSLA 分量。支持 rgb()、rgba()、hsl()、hsla()、十六进制和命名颜色。

数组与集合

  • selector(scope)：返回限定在指定元素或 ref 内的选择器函数，适合组件内使用，避免选择器匹配整个文档。
  • toArray(value, scope?)：把选择器字符串、NodeList、HTMLCollection、单个元素或数组转换为真正的数组，可选择限定作用域。
  • pipe(...functions)：组合函数，pipe(f1, f2, f3)(value) 等价于 f3(f2(f1(value)))，用于串联变换链。
  • wrap(min, max, value?)：把数值环绕到 min–max 区间（含 min、不含 max），适合无限滚动或循环值。省略 value 时返回函数。
  • wrapYoyo(min, max, value?)：在区间内环绕并在端点反弹，适合往返取值。省略 value 时返回函数。

使用方式

所有方法都挂在 gsap.utils 下，例如 gsap.utils.clamp()。多数函数在省略待处理数值参数时返回一个可复用函数，适合同一配置反复使用的场景，如滚动处理、鼠标移动处理或 tween 回调。random 是例外，要以可复用函数形式使用时，应在最后传 true。

适用场景

资料列出：编写或审查使用 gsap.utils 进行数学运算、数组或集合处理、单位解析和数值映射的动画代码，例如把滚动映射为数值、随机化、吸附到网格、归一化输入。可与 gsap-core、gsap-timeline、gsap-scrolltrigger 配合构建动画；CustomEase 等缓动工具属于 gsap-plugins。

限制与注意事项

资料提醒：mapRange 与 normalize 只处理数字，不处理单位，涉及单位时应使用 getUnit 或 unitize；不要依赖未文档化的行为，应坚持使用已文档化的 API。资料未提供安装命令、版本号、收费与价格、平台要求等信息，这些暂未提供。