gsap-utils

gsap.utils

何时使用此技能

在编写或审查使用 gsap.utils 进行数学运算、数组/集合处理、单位解析或动画值映射（例如将滚动映射到某个值、随机化、对齐到网格或归一化输入）的代码时应用。

相关技能： 构建动画时与 gsap-core、gsap-timeline 和 gsap-scrolltrigger 一起使用；CustomEase 和其他缓动工具位于 gsap-plugins 中。

概述

gsap.utils 提供纯辅助函数；无需注册。在补间变量（例如基于函数的值）、ScrollTrigger 或 Observer 回调中，或在任何驱动 GSAP 的 JS 中使用。所有工具都位于 gsap.utils 上（例如 gsap.utils.clamp()）。

省略值：函数形式。 许多工具接受要转换的值作为最后一个参数。如果省略该参数，该工具将返回一个函数，该函数稍后接受该值。当需要对多个值使用相同配置进行 clamp、map、normalize 或 snap 时（例如在鼠标移动处理程序或补间回调中），请使用函数形式。例外情况：random()——传递 true 作为最后一个参数以获取可重用函数（不要省略值）；请参阅 random()。

// 带值：返回结果
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)。

gsap.utils.clamp(0, 100, 150); // 100
gsap.utils.clamp(0, 100, -10); // 0

let clampFn = gsap.utils.clamp(0, 100);
clampFn(150); // 100

mapRange(inMin, inMax, outMin, outMax, value?)

将值从一个范围映射到另一个范围。用于转换滚动位置、进度 (0–1) 或输入范围到动画范围。省略 value 以获取一个函数：mapRange(inMin, inMax, outMin, outMax)(value)。

gsap.utils.mapRange(0, 100, 0, 500, 50);  // 250
gsap.utils.mapRange(0, 1, 0, 360, 0.5);   // 180（进度转角度）

let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
mapFn(50);  // 250

normalize(min, max, value?)

返回归一化到 0–1 范围内的值。是目标范围为 0–1 时映射的逆操作。省略 value 以获取一个函数：normalize(min, max)(value)。

gsap.utils.normalize(0, 100, 50);   // 0.5
gsap.utils.normalize(100, 300, 200); // 0.5

let normFn = gsap.utils.normalize(0, 100);
normFn(50); // 0.5

interpolate(start, end, progress?)

在给定进度 (0–1) 下对两个值进行插值。支持数字、颜色和具有匹配键的对象。省略 progress 以获取一个函数：interpolate(start, end)(progress)。

gsap.utils.interpolate(0, 100, 0.5);       // 50
gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // 中间颜色
gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }

let lerp = gsap.utils.interpolate(0, 100);
lerp(0.5); // 50

随机与对齐

random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])

返回 minimum–maximum 范围内的随机数，或 array 中的随机元素。可选的 snapIncrement 将结果对齐到最近的倍数（例如 5 → 5 的倍数）。要获取可重用函数，请传递 true 作为最后一个参数 (returnFunction)；返回的函数不带参数，每次调用返回一个新的随机值。这是唯一使用 true 作为函数形式而不是省略值的工具。

// 立即值：范围内的数字
gsap.utils.random(-100, 100);        // 例如 42.7
gsap.utils.random(0, 500, 5);        // 0–500，对齐到最近的 5

// 可重用函数：传递 true 作为最后一个参数
let randomFn = gsap.utils.random(-200, 500, 10, true);
randomFn();  // 范围内的随机值，对齐到 10
randomFn();  // 另一个随机值

// 数组：随机选取一个值
gsap.utils.random(["red", "blue", "green"]);  // "red"、"blue" 或 "green"
let randomFromArray = gsap.utils.random([0, 100, 200], true);
randomFromArray();  // 0、100 或 200

补间变量中的字符串形式： 使用 "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])" });

snap(snapTo, value?)

将值对齐到 snapTo 的最近倍数，或对齐到允许值数组中的最近值。省略 value 以获取一个函数：snap(snapTo)(value)（或 snap(snapArray)(value)）。

gsap.utils.snap(10, 23);     // 20
gsap.utils.snap(0.25, 0.7);  // 0.75
gsap.utils.snap([0, 100, 200], 150); // 100 或 200（数组中最接近的）

let snapFn = gsap.utils.snap(10);
snapFn(23); // 20

在补间中用于网格或步进动画：

gsap.to(".x", { x: 200, snap: { x: 20 } });

shuffle(array)

返回一个包含相同元素但顺序随机的新数组。用于随机化顺序（例如从 "random" 开始交错并复制）。

gsap.utils.shuffle([1, 2, 3, 4]); // 例如 [3, 1, 4, 2]

distribute(config)

返回一个函数，该函数根据目标在数组（或网格）中的位置为每个目标分配一个值。内部用于高级交错；当需要在多个元素之间分配值时使用（例如 scale、opacity、x、delay）。返回的函数接收 (index, target, targets)——既可以手动调用它，也可以将结果直接传递给补间；GSAP 会为每个目标调用它，参数为 index、element 和 array。

配置（全部可选）：

属性	类型	描述
base	Number	起始值。默认 0。
amount	Number	在所有目标之间分配的总量（加到 base 上）。例如 amount: 1 有 100 个目标 → 每个之间 0.01。使用 each 代替可为每个目标设置固定步长。
each	Number	每个目标之间增加的量（加到 base 上）。例如 each: 1 有 4 个目标 → 0, 1, 2, 3。使用 amount 代替可分割总量。
from	Number | String | Array	分配开始的位置：索引，或 "start"、"center"、"edges"、"random"、"end"，或类似 [0.25, 0.75] 的比例。默认 0。
grid	String | Array	使用网格位置而不是平面索引：[rows, columns]（例如 [5, 10]）或 "auto" 自动检测。省略则为平面数组。
axis	String	对于网格：限制为一个轴（"x" 或 "y"）。
ease	Ease	沿缓动曲线分配值（例如 "power1.inOut"）。默认 "none"。

在补间中： 将 distribute(config) 的结果作为属性值传递；GSAP 会为每个目标调用该函数，参数为 (index, target, targets)。

// 缩放：中间元素 0.5，外边缘 3（从中心分配 2.5）
gsap.to(".class", {
  scale: gsap.utils.distribute({
    base: 0.5,
    amount: 2.5,
    from: "center"
  })
});

手动使用： 使用 (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);

更多信息请参阅 distribute()。

单位与解析

getUnit(value)

返回值的单位字符串（例如 "px"、"%"、"deg"）。用于归一化或转换值时。

gsap.utils.getUnit("100px");   // "px"
gsap.utils.getUnit("50%");     // "%"
gsap.utils.getUnit(42);        // ""（无单位）

unitize(value, unit)

在数字后附加单位，如果值已有单位则原样返回。用于构建 CSS 值或补间结束值时。

gsap.utils.unitize(100, "px");  // "100px"
gsap.utils.unitize("2rem", "px"); // "2rem"（不变）

splitColor(color, returnHSL?)

将颜色字符串转换为数组：[red, green, blue] (0–255)，或 [red, green, blue, alpha]（当存在或需要 alpha 时返回 4 个元素的 RGBA）。传递 true 作为第二个参数 (returnHSL) 以改为获取 [hue, saturation, lightness] 或 [hue, saturation, lightness, alpha] (HSL/HSLA)。适用于 "rgb()"、"rgba()"、"hsl()"、"hsla()"、十六进制和命名颜色（例如 "red"）。用于动画颜色分量或构建渐变时。请参阅 splitColor()。

gsap.utils.splitColor("red");                    // [255, 0, 0]
gsap.utils.splitColor("#6fb936");                // [111, 185, 54]
gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5]（4 个元素）
gsap.utils.splitColor("#6fb936", true);          // [94, 55, 47]（HSL：色调、饱和度、亮度）

数组与集合

selector(scope)

返回一个作用域选择器函数，该函数仅在给定元素（或 ref）内查找元素。在组件中使用，以便像 ".box" 这样的选择器仅匹配该组件的后代，而不是整个文档。接受 DOM 元素或 ref（例如 React ref；处理 .current）。

const q = gsap.utils.selector(containerRef);
q(".box");        // container 内的 .box 元素数组
gsap.to(q(".circle"), { x: 100 });

toArray(value, scope?)

将值转换为数组：选择器字符串（作用域到元素）、NodeList、HTMLCollection、单个元素或数组。当将混合输入传递给 GSAP（例如目标）并且需要真实数组时使用。

gsap.utils.toArray(".item");           // 元素数组
gsap.utils.toArray(".item", container); // 作用域到 container
gsap.utils.toArray(nodeList);          // [ ... ] 来自 NodeList

pipe(...functions)

组合函数：pipe(f1, f2, f3)(value) 返回 f3(f2(f1(value)))。在补间或回调中应用转换链时使用（例如 normalize → mapRange → snap）。

const fn = gsap.utils.pipe(
  (v) => gsap.utils.normalize(0, 100, v),
  (v) => gsap.utils.snap(0.1, v)
);
fn(50); // 归一化后对齐

wrap(min, max, value?)

将值包裹到 min–max 范围内（包含 min，排除 max）。用于无限滚动或循环值。省略 value 以获取一个函数：wrap(min, max)(value)。

gsap.utils.wrap(0, 360, 370);  // 10
gsap.utils.wrap(0, 360, -10);   // 350

let wrapFn = gsap.utils.wrap(0, 360);
wrapFn(370); // 10

wrapYoyo(min, max, value?)

将值包裹在范围内并具有悠悠效果（在两端反弹）。用于在范围内的来回运动。省略 value 以获取一个函数：wrapYoyo(min, max)(value)。

gsap.utils.wrapYoyo(0, 100, 150); // 50（反弹回来）

let wrapY = gsap.utils.wrapYoyo(0, 100);
wrapY(150); // 50

最佳实践

• ✅ 当相同范围/配置被多次使用时（例如滚动处理程序、补间回调），省略值参数以获取可重用函数：let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress)。
• ✅ 使用 snap 进行网格对齐或基于步进的值；当 GSAP 或你的代码需要从选择器或 NodeList 获取真实数组时，使用 toArray。
• ✅ 在组件中使用 gsap.utils.selector(scope)，以便选择器作用域到容器或 ref。

不要做的事

• ❌ 假设 mapRange / normalize 处理单位；它们只对数字工作。当单位重要时使用 getUnit / unitize。
• ❌ 覆盖或依赖未文档化的行为；坚持使用文档化的 API。

了解更多

https://gsap.com/docs/v3/HelperFunctions