gsap-utils

gsap.utils

何时使用此技能

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

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

概述

gsap.utils 提供纯辅助函数，无需注册。可在补间变量（例如基于函数的值）、ScrollTrigger 或 Observer 回调中，或任何驱动 GSAP 的 JavaScript 中使用。所有方法都在 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?)

将值约束在最小值和最大值之间。省略 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 范围内的随机数，或数组中的随机元素。可选的 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 会为每个目标调用它，传入索引、元素和数组。

配置（全部可选）：

属性	类型	描述
`base`	数字	起始值。默认 `0`。
`amount`	数字	在所有目标上分布的总量（加到 base 上）。例如 `amount: 1` 配合 100 个目标 → 每个之间 0.01。使用 each 为每个目标设置固定步长。
`each`	数字	每个目标之间增加的量（加到 base 上）。例如 `each: 1` 配合 4 个目标 → 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"`。

在补间中： 将 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?)

将颜色字符串转换为数组：[红色, 绿色, 蓝色]（0–255），或 [红色, 绿色, 蓝色, 透明度]（当存在或需要透明度时为 4 个元素）。传递 true 作为第二个参数（returnHSL）以获取 [色相, 饱和度, 明度] 或 [色相, 饱和度, 明度, 透明度]（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");        // 容器内的 .box 元素数组
gsap.to(q(".circle"), { x: 100 });

toArray(value, scope?)

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

gsap.utils.toArray(".item");           // 元素数组
gsap.utils.toArray(".item", 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。

你可能还喜欢

fix

247Kfrontend

Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.

react

获取

vue-patterns

240Kfrontend

Vue.js 3 Composition API patterns, component architecture, reactivity best practices, Pinia state management, Vue Router navigation, and Nuxt SSR patterns. Activates for Vue, Nuxt, Vite, or Pinia projects. Use when building or reviewing Vue 3, Nuxt, or Pinia code — Composition API, reactivity, or router navigation.

affaan-m

获取

fix