GSAP教程之gsap.utils详解

gsap.utils  提供了非常实用的方法集合，其中过很多可以返回函数，以便直接在tween中使用，特别是多对象动画时，将会每个目标调用一次，而不是为每个目标使用相同值。
例子：
为每个目标动画调用random产生不同的y值。

gsap.to(".box", {
  y: "random(20, 200)"
})

checkPrefix(property)

提供任意CSS属性名，返回该属性的适当的，带有浏览器前缀的版本。如果不需要前缀，它将返回原始的属性名。如果属性不存在，它将返回 undefined 。

• Property（String）: CSS属性名
• 返回值: String

例子：
它可能返回 filter , WebfitFilter ,或 MozFilter ， 具体将依据浏览器。

gsap.utils.checkPrefix("filter");

clamp()

• clamp(minimum, maximum, valueToClamp)
  给定一个值，如果这个值小于最小值，则返回最小值，如果大于最大值，则返回最大值，如果在最小值和最大值之间，则返回原本给定的值。
  • minimum(Number): 最小值
  • maximum(Number): 最大值
  • valueToclamp(Number): 给定的值
  • 返回值：Number

例子：

gsap.utils.clamp(0, 100, 105)  //返回100
gsap.utils.clamp(0, 100, -50) //返回0
gsap.utils.clamp(0, 100, 20) //返回20

• clamp(minimum, maximum)
  省略valueToClamp 参数，将返回一个可用函数，该函数会记录最大最小值，方便快速的根据需要多次执行clamp。
  • minimum(Number): 最小值
  • maximum(Number): 最大值
  • 返回值：Function

例子：

let clamper = gsap.utils.clamp(0, 100);
clamper(105)  //返回100
clamper(-50) //返回0
clamper(20) //返回20

distribute(vars)

返回一个函数，该函数依据参数给一个数组个项分配值。

• vars 参数：
• base(Number): 开始值，默认值：0
• amount(Number): 要在目标上分配的总值。

 From , grid , axis , ease  可参考stagger详解。
例子1：
box对象从第一个到最后一个，从10到200，分配（方式依据ease， none表示平均）。也就是：假设有8个box, 第一个box的y运动到10， 第2个box运动到10 +200/(8-1), 公式为：10 + 200/(8-1)*i, 索引从0开始，注意这里是平均分配（ ease: none ）。

gsap.to(".box", {
  y: gsap.utils.distribute({
    base: 10,
    amount: 200,
    ease: "none"
  })
})

例子2：
value 即为第3个（索引是2）box的分配值。
 let distributor = gsap.utils.distribute({ base: 10, amount: 200, ease: "none" }); let targets = gsap.utils.toArray(".box"); let value = distributor(2, targets[2], targets); 

getUnit()

返回给定字符串的单位，其中数字排在前面，然后是单位。
例子：

gsap.utils.getUnit("50%"); //返回%
gsap.utils.getUnit("100vw"); //返回vw

interpolate()

• interpolate(startValue, endValue, progress)
  它可以在任意两个值（数字，颜色，字符串，数组，具有多个属性的对象...几乎任何类型）之间线性插值，progress 是介于0和1之间的进度值，0.5介入中间，根据progress 返回中间值。
  • startValue: 开始值。任意类型（数字，颜色，字符串，数组，对象等）
  • endValue: 结束值。任意类型。
  • progress: 进度值。介于0和1之间。

例子1：

gsap.utils.interpolate(0, 500, 0.5); //返回250
gsap.utils.interpolate(0, 500, 0.75); //返回375
gsap.utils.interpolate(0, 500, 1); //返回500

例子2：

gsap.utils.interpolate("20px", "40px", 0.5); // 返回"30px"
gsap.utils.interpolate("red", "blue", 0.5); // 返回"rgba(128,0,128,1)"

例子3：

gsap.utils.interpolate(
  {a:0, b:10, c:"red"},
  {a:100, b:20, c:"blue"},
  0.5);
  // 返回{a: 50, b: 15, c: "rgba(128,0,128,1)"}

• interpolate(array, progress)

例子1：

gsap.utils.interpolate([10, 20, 100], 0.5); //返回20
gsap.utils.interpolate(["red", "green", "blue"], 0.5); //返回"green"

例子2：
0.5时返回20，20到100部分又占0.25/0.5为40，即20+40=60

gsap.utils.interpolate([10, 20, 100], 0.75); //返回60

• interpolate(startValue, endValue) 或 interpolate(array)
  返回一个函数，参数为progress

例子1：

let interp = gsap.utils.interpolate(0, 100);
interp(0.5); // 50
interp(0.25); // 25
interp(1);  // 100

例子2：

let interp = gsap.utils.interpolate({a:0, b:10, c:"red"}, {a:100, b:20, c:"blue"});
interp(0.5); // {a: 50, b: 15, c: "rgba(128,0,128,1)"}

例子3：

let interp = gsap.utils.interpolate([100, 50, 500]); //notice we didn't provide a progress value
interp(0.5); // 50
interp(0.75); // 275

例子4：

let interp = gsap.utils.interpolate(["red", "green", "blue"]);
interp(0.25); // "rgba(128,64,0,1)"

mapRange()

将数字在一个范围内的相对位置映射到另一个范围中的等效位置。例如：范围0到100，50位于中间，如果映射到0到500的范围，则为250.

• mapRange(inMin, inMax, outMin, outMax, valueToMap)
  • inmin(Number): 初始范围的下限值。
  • inMax(Number): 初始范围的上限值。
  • outMin(Number): 目标范围的下限值。
  • outMax(Number): 目标范围的上限值。
  • valueToMap(Number): 需要映射的值。
  • 返回值（Number）： 映射到目标范围的值。

例子：

gsap.utils.mapRange(0, 10, 0, 100, 5) //返回50

• mapRange(inMin, inMax, outMin, outMax)
  返回映射函数，参数为：valueToMap（需要映射的值）。

例子：

let mapper = gsap.utils.mapRange(0, 10, 0, 100);
mapper(2); //返回20
mapper(5); //返回50

normalize()

将提供范围内的值映射到0到1之间的对应位置。

• normalize(minimum, maximum, valueToNormalize)
  • minimum(Number): 提供范围的下限值。
  • maximum(Number): 提供范围的上限值。
  • valueToNormalize(Number): 需要映射的值。
  • 返回值（Number）：映射到0到1之间的值。

例子：

gsap.utils.normalize(0, 100, 20); //返回0.2

• normalize(minimum, maximum)

返回映射函数，参数为：valueToNormalize (需要映射的值)。
例子：

let mapper = gsap.utils.normalize(0, 100);
mapper(20); //返回0.2
mapper(50); //返回0.5

pipe()

将多个函数调用串在一起，将结果从一个传递到下一个。
例子1：

let transform = gsap.utils.pipe(func1, func2, func3);
let output = transform(input);

等效于：

let output = func1(func2(func3(input)));

例子2：
将20夹在范围0到100间，然后在映射到0到浏览器宽度之间。适用于等比计算。

let transformer = gsap.utils.pipe(
  gsap.utils.clamp(0, 100),
  gsap.utils.mapRange(0, 100, 0, window.innerWidth)
);
transformer(20)

random()

获取指定范围内的随机数。

• random(minimum, maximum, [, snapIncrement, returnFunction])
  • minimum(Number): 指定范围的下限。
  • maximum(Number): 指定范围的上限。
  • snapIncrement(Number, 可选)： 增量，获取的随机数为增量倍数。
  • returnFunction(Function, 可选)： 是否返回随机函数，可随时调用，默认值：false。

例子1：
返回0到100之间的随机数。

gsap.utils.random(0, 100); //返回83.95008

例子2：
返回0到100的随机数，并且随机数为10的倍数。

gsap.utils.random(0, 100, 10); //返回30

例子3：

let random = gsap.utils.random(0, 100, true);
random(); //返回29.91366
random(); //返回20.86469

例子4：

let random = gsap.utils.random(0, 100, 10, true);
random(); //返回20
random(); //返回70

• random(array, [, returnFunction])
  从数组中随机选择一项。
  • array(任意类型数组)：供选择的数组。

例子：

gsap.utils.random(["red", "blue", "green"]);
gsap.utils.random([0, 100, 200]);

• 字符串形式

在tween中，还可以使用类似  random(-100, 100) 的字符串形式。
例子1：
这样所有的box都是移动统一的高度，random 只会调用一次。

gsap.to(".box", {
  y: gsap.utils.random(10, 300)
});

而这样返回的是function, 会调用很多次，每个box移动的高度都是随机出来。

gsap.to(".box", {
  y: gsap.utils.random(10, 300, true)
});

或使用字符串，也是每个box高度都随机出来。

gsap.to(".box", {
  y: "random(10, 300)"
});

例子2：
每个box颜色都随机从数组中挑选。

gsap.to(".box", {
  backgroundColor: "random([red, blue, green])"
});

Shuffle(array)

对指定数组进行洗牌，返回原数组（不重新创建数组）。
例子：

gsap.utils.shuffle([1, 2, 3, 4, 5, 6]); //返回[1, 2, 5, 6, 3, 4]

snap()

获取和增量或数组中最接近的值。获取值需要在增量的半径测量中。

• snap(snapIncrement[, valueToSnap])
  • snapIncrement(Number): 增量值。
  • valueToSnap(Number, 可选)： 匹配值。缺失该参数，则返回函数，供随时调用。

例子1：

gsap.utils.snap(10, 29); //返回30
gsap.utils.snap(10, 25); //返回30
gsap.utils.snap(10, 24); //返回20

例子2：

let snap = gsap.utils.snap(10);
snap(29); //返回30
snap(25); //返回30
snap(24); //返回20

• snap(array[, valueToSnap])
  • array(Array): 需要snap的数组。

例子1：
注意75和300的分界值特点。

gsap.utils.snap([100, 50, 500], 65); //返回50
gsap.utils.snap([100, 50, 500], 75); //返回50  分界值
gsap.utils.snap([100, 50, 500], 76); //返回100
gsap.utils.snap([100, 50, 500], 299); //返回100
gsap.utils.snap([100, 50, 500], 300); //返回500  分界值
gsap.utils.snap([100, 50, 500], 1000); //返回500

例子2：

let snap = gsap.utils.snap([100, 50, 500]);
snap(65); //50

• snap(objectWithRadius[, valueToSnap])
  • objectWithRadius(Object): 一个具有数值radius属性和值数组的对象，类似{values: [0, 20, 60], radius: 5}或{increment: 500, radius: 150}。

例子1：
注意半径概念

let snap = gsap.utils.snap({values: [0, 100, 300], radius: 20});
snap(-21); //返回-21
snap(-20); //返回0
snap(20); //返回0
snap(21); //返回21
snap(79); //返回79
snap(80); //返回100
snap(120); //返回100
snap(121); //121
snap(279); //返回279
snap(280); //返回300

例子2：
提供的点在数组中的哪个点的半径圆内，就snap到哪个点。 换句话说就是，提供的点和数组中的点的距离相比，小于半径的点。

let snap = gsap.utils.snap({
  values: [{x: 0, y: 0}, {x: 10, y: 10}, {x: 20, y: 20}],
  radius: 5});
snap({x: 4, y: 4}); //返回{x: 4, y: 4}
snap({x: 8, y: 8}); //返回{x: 10, y: 10}

例子3：

let snap = gsap.utils.snap({increment: 500, radius: 150});
snap(150); //返回0
snap(151); //返回151
snap(349); //返回349
snap(350); //返回500
snap(650); //返回500
snap(651); //返回651
snap(849); //返回849
snap(850); //返回1000

等效于：

gsap.utils.snap({value: [-500, 0, 500, 1000, 1500], radius: 150})

splitColor(color, returnHSL)

将基于字符传的颜色值转换为由  [red, gree, blue] 组成的RGB颜色值。如果有alpha值，则该值位于数组最后一位。

• color(String): 需要转换的字符串颜色值。
• returnHSL(Boolean, 可选): 如果true , 则返回的格式为HSL/HSLA（色相，饱和度，亮度， 透明度）

例子1：

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]

例子2：

gsap.utils.splitColor("#6fb936", true); // [94, 55, 47]

toArray(targets)

将选择器文本，对象（或选择器）数组，节点列表，对象或任意数组（如jquery结果）转换为数组。

• targets(Object|String|NodeList|Array): 需要转换的目标，它可以是选择器文本，对象，节点列表，JQ对象 等。

例子：

gsap.utils.toArray(".class");

unitize(function, unit)

为提供的函数计算的值加上单位。

• function(Function): 提供的函数，其计算结果加单位。
• unit(String, 可选)： 单位，如果省略，将应用输入的原始单位。
• 返回值(Function): 返回的函数。

例子1：

let random = gsap.utils.unitize(gsap.utils.random(0, 100, true), "px");
random(); //返回 "64.46503px"

例子2：

let clamper = gsap.utils.unitize(gsap.utils.clamp(0, 100), "px");
clamper(200); //返回 "100px"

例子3：
unitize 先剥离单位，再将值传入 clamp 计算后，再加上单位

let transfer = gsap.utils.unitize(gsap.utils.clamp(0, 100));
transfer("150px"); //返回"100px"

wrap()

将一个数字（或数组索引）放入指定的范围，这样，当它超过最大值时，它将换回起始位置；当它小于最小值时，它将换回到结束位置。

• wrap(minimum, maximum[, value])
  • minimum(Number): 最小值。
  • maximum(Number): 最大值。
  • value(Number，可选): 放入范围的数字。
  • 返回值：返回计算后的数字。若第3个参数不传，则返回计算的函数。

例子1：

let wrapper = gsap.utils.wrap(0, 10)
wrapper(0); //返回0
wrapper(4); //返回4
wrapper(10); //返回0
wrapper(14); //返回4
wrapper(20); //返回0
wrapper(24); //返回4
wrapper(-1); //返回9
wrapper(-10); //返回0

例子2：

gsap.utils.wrap(0, 10, 4); //返回4

• wrap(array[, index])
  • array(Array): 指定范围的数组，可以时字符串，数字，等任何类型的数组。
  • index(Number, 可选): 索引值。
  • 返回值: 可以是任意类型，由提供的数组范围类型决定，当索引超过数组长度，换回的数组的起始位置，小于数组的起始位置（索引0），则换回数组的结束位置。若不提供第3个参数，则返回计算的函数。

例子1：

let wrapper = gsap.utils.wrap(["red", "blue", "green"]);
wrapper(0); //返回"red"
wrapper(2); //返回"green"
wrapper(3); //返回"red"
wrapper(6); //返回"red"
wrapper(-1); //返回"green"
wrapper(-3); //返回"red"

例子2：

let wrapper = gsap.utils.wrap([10, 50, 30]);
wrapper(0); //返回10
wrapper(2); //返回30
wrapper(3); //返回10

例子3：

gsap.utils.wrap(["red", "blue", "green"], 2); //返回"green"

例子4：
实际应用，如果box 的超过浏览器高度，则从0开始运动。

let wrapper = gsap.utils.unitize(gsap.utils.wrap(0, window.innerHeight));
gsap.to(".box", {
  duration: 5,
  y: 10000,
  modifiers: {
    y: y => wrapper(y)
  }
});

wrapYoyo()

将一个数字（或数组索引）放入指定的范围，这样，当它超过最大值时，它将朝起始位置前进；当它小于最小值时，它将朝结束位置前进。和warp()的方向不同。

• wrapYoyo(minimum, maximum[, value])
  • minimum(Number): 最小值。
  • maximum(Number): 最大值。
  • value(Number，可选): 放入范围的数字。
  • 返回值：返回计算后的数字。若第3个参数不传，则返回计算的函数。

例子：

let wrapper = gsap.utils.wrapYoyo(0, 10)
wrapper(0); //返回0
wrapper(4); //返回4
wrapper(10); //返回10
wrapper(11); //返回9
wrapper(20); //返回0
wrapper(-1); //返回1
wrapper(-10); //返回10

• wrapYoyo(array[, index])
  • array(Array): 指定范围的数组，可以时字符串，数字，等任何类型的数组。
  • index(Number, 可选): 索引值。
  • 返回值: 可以是任意类型，由提供的数组范围类型决定，当索引超过数组长度，朝数组的起始位置运动，小于数组的起始位置（索引0），则朝数组的结束位置运动。若不提供第3个参数，则返回计算的函数。

例子1：

let wrapper = gsap.utils.wrapYoyo(["red", "blue", "green"]);
wrapper(0); //返回"red"
wrapper(2); //返回"green"
wrapper(3); //返回"blue"
wrapper(6); //返回"green"
wrapper(-1); //返回"blue"
wrapper(-3); //返回"blue"

例子2：
相较使用 wrap ，它是来回往复运动。

let wrapper = gsap.utils.unitize(gsap.utils.wrapYoyo(0, window.innerHeight));
gsap.to(".box", {
  duration: 5,
  y: 10000,
  modifiers: {
    y: y => wrapper(y)
  }
});