GSAP教程之Tween详解

韦阳晖

2023-12-01

Tween是所有动画的实例，创建一个实例的方法有：

gsap.to();
gsap.from();
gsap.fromTo();

具体请参考gsap.to, gsap.from与gsap.fromTo详解。

例子：

let tween = gsap.to(".box", {
  duration: 2,
  y: 200
});

tween.kill()

Tween属性详解

tween.data

存储数据。在vars参数里设置。具体参考gsap.to, gsap.from与gsap.fromTo 详解中关于vars参数data的设置。
例子：

let tween = gsap.to(".box", {
  y: 200,
  data: {x: 10, y: 10}
});

tween.data //{x: 10, y: 10}

tween.ratio (read-only)

在通过ease之后进程（介于0和1之间，其中0.5在中间，）。但是在ease为back，elastic时，这个值有可能超过0-1的范围。
例子：

let easeFunc = gsap.parseEase("power2.out");
let tween = gsap.to({foo: 0}, {foo: 10, duration: 1, ease: "power2.out"});
tween.pause(0.5); // pause at 0.5 seconds which is halfway in this 1-second tween

console.log(tween.progress());           // 0.5
console.log(tween.ratio);                // 0.875
console.log(easeFunc(tween.progress())); // 0.875

tween.vars

传递到构造函数中的配置对象，包含所有要设置动画的属性。具体参考gsap.to, gsap.from与gsap.fromTo 详解中关于vars参数详解。

Tween方法详解

tween.delay()

设置或获取动画的延迟时间。
例子：

let delay = tween.delay(); //获取当前延迟
tween.delay(2); //设置延迟

tween.delay()
获取动画的延迟时间。返回值：Number。
Tween.delay(value)
- value(Number): 延迟时间。
- 返回值：Tween(Self)

设置动画的延迟时间。

tween.duration()

设置或获取动画的时长。

let duration = tween.duration(); //获取当前时长
tween.duration(2); //设置时长

tween.duration()
获取动画的时长。返回值： Number
tween.duration(value)
设置动画时长。
- value(Number): 时长值。
- 返回值：Tween(Self)

tween.endTime()

根据父时间轴返回动画的完成时间。
例子：

let timeline = gsap.timeline();
let tween = gsap.to(".box", {
  delay: 1,
  duration: 2,
  y: 200
});
timeline.add(tween, 0.5);
tween.endTime(); //返回3.5

tween.eventCallback()

设置或过去事件回调。如onComplete，onUpdate等，以及传递给回调的参数。

tween.eventCallback(type)
获取回调事件。
- type(String): 回调的关键字。如onStart，onComplete，onUpdate等。

例子：

let tween = gsap.to(".box", {
  y: 200,
  onUpdate: function(){
    console.log("onUpdate");
  }
});

tween.eventCallback("onUpdate"); //返回设置的函数

tween.eventCallback(type, callback[, params])
- type(String): 事件关键字。
- callback(Function): 回调函数。如果为null，则清除原有事件。
- params(Array, 可选): 参数数组，任意类型。不传则无参数。
- 返回值：Tween(Self)

例子1：

tween.eventCallback("onUpdate", function(p1, p2){
  console.log(p1); //"param1"
  console.log(p2); //"param2"
}, ["param1", "param2"]);

等效于：

let tween = gsap.to(".box", {
  y: 200,
  onUpdate: function(p1, p2){
    console.log(p1); //"param1"
    console.log(p2); //"param2"
  },
  onUpdateParams: ["param1", "param2"]
});

例子2：
清除动画原有的回调事件

tween.eventCallback("onUpdate", null);

tween.invalidate()

刷新动画的开始结束值。如果想重新启动动画，不还原到之前的开始结束值，这就非常有用。
返回值：Tween(Self)。
例子：
如果在restart()之前不执行invalidate()，那么动画每次都是从0运动到100。而执行了invalidate()，动画每次都会刷新开始结束值，动画将0->100, 100->200, 200->300 …

gsap.to(".box", {
  duration: 2,
  y: "+=100",
  onComplete: function(){
  this.invalidate();
  this.restart();
  }
});

tween.isActive()

获取动画是否处理活动状态（播放状态）。返回值： Boolean

tween.iteration()

获取或设置动画的迭代次数。

tween.iteration()
获取迭代次数，返回值：Number。

例子：

gsap.to(".box", {
  duration: 2,
  y: "+=100",
  repeat: 5,
  onStart: function(){
    console.log(this.iteration() + "/onStart");
  },
  onRepeat: function(){
    console.log(this.iteration() + "/onRepeat");
  }
});

/// console 输出
1/onStart
2/onRepeat
3/onRepeat
4/onRepeat
5/onRepeat
6/onRepeat

由于onRepeat只会在repeat时调用，所以这里用onStart来打印次数。

tween.iteration(value)
设置迭代次数。
- Value(Number): 次数。
- 返回值： Tween(Self)

例子：

tween.iteration(2);

///输出
3/onRepeat
4/onRepeat
5/onRepeat
6/onRepeat

tween.kill()

根据参数完全或部分终止动画。立即停止动画，并从其父timeline中删除动画并释放。返回值：Tween

tween.kill()
完全终止动画
tween.kill(target[, propertiesList])
- target(String|Array|Object): 需要停止特定目标的动画，参考gsap.to的targets参数。
- propertiesList(String): 需要停止动画的特定属性。例如：“x,y”，“rotate”。

例子1：
停止第一个box的动画。支持选择器文本（具体可参考document.querySelectorAll()的用法）

tween.kill(".box:nth-child(1)");

例子2：
停止id=box2的动画，或同时停止2个box的动画。

let el2 = document.getElementById("box2");
let el4 = document.getElementById("box4");
tween.kill(el2);
tween.kill([el2, el4])

例子3：
停止所有动画的x,y动画。

tween.kill(null, "x,y");

例子4：
前5个box停止y动画

tween.kill(".box:nth-child(-n+5)", "y")

tween.pause(atTime, suppressEvents)

暂停动画，可以选择跳到特定时间。

atTime(Number, 可选): 动画跳到的指定时间，如未指定，则暂停在初始位置。默认值：null。
suppressEvents(Boolean, 可选): 如果设置true, 当移动到指定位置时，不触发任何回调事件。默认值：true。
返回值：Tween。

例子：

tween.pause(); //暂停动画
tween.pause(1); //移动到1秒位置，并暂停动画
tween.pause(1, false); //移动到1秒位置，并暂停，且可以出发相关回调

tween.paused(value)

获取或设置动画的暂停状态。

value(Boolean，可选)：想要设置的暂停状态，不指定该参数，则返回当前暂停状态。
返回值（Boolean|Tween）：不设置参数，则返回暂停状态，设置参数，则返回Tween。

例子1：

tween.paused(); //返回暂停状态
tween.paused(true); //设置暂停状态

例子2：
若有一按钮，点击开始动画，再点击暂停动画，来回切换。

tween.paused(!tween.paused());

tween.play(from, suppressEvents)

开始播放，可以选择从指定时间开始播放。默认是从当前位置播放。

from(Number): 指定开始播放的时间（位置）。不指定该参数，则从当前所在位置播放。默认值：null。
suppressEvents(Boolean, 可选): 如果为true, 则当移动到指定位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值：Tween

例子：

tween.play();  //开始播放
tween.play(2); //从2秒位置开始播放
tween.play(2, false); //从2秒位置开始播放，并且触发相关回调

tween.progress(value, suppressEvents)

获取或设置动画的进度，该进度之介于0和1之间，其中0处于开始位置，0.5处于一半的位置，1处于完成位置。

value(Number): 进度值，介于0和1之间。
suppressEvents(Boolean, 可选)：如果为true, 则当移动到指定位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值（Number或Tween）：如果不指定value参数，则返回当前的进度值（Number），若指定则返回Tween。

例子：

tween.progress();  //返回0.3，当前的进度值
tween.progress(0.5); //设置播放进度为0.5
tween.progress(0.5, false); //设置播放进度为0.5，且触发相关回调

tween.repeat(value)

获取或设置动画的重复次数。

value(Number): 重复次数。
返回值（Number或Tween）: 如果不指定value参数，则返回重复次数（Number），或指定则返回Tween。

例子：

tween.repeat(); //返回重复次数
tween.repeat(2); //设置重复2次

tween.repeatDelay(value)

获取或设置动画每次重复之间的延迟秒数。

value(Number): 延迟秒数。
返回值（Number或Tween）: 如果不指定value参数，则返回当前的重复延迟秒数（Number），若指定则返回Tween。

例子：

tween.repeatDelay(); //返回重复延迟时间
tween.repeatDelay(2); //设置重复延迟时间为2秒

tween.restart(includeDelay, suppressEvents)

重新播放动画。

includeDelay(Boolean): 重新播放动画是否遵守延迟（如果有）。例如，如果tween有1秒的延迟，那么restart后是否也需要延迟1秒才开始播放动画。默认值：false，不遵守延迟，设置true，则遵守延迟。
suppressEvents(Boolean, 可选)：如果为true, 则当移移动到开始位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值：Tween

例子：

tween.restart(); //立即开始播放，不遵守延迟
tween.restart(true); //遵守延迟
tween.restart(true, false); //遵守延迟，并触发相关回调

###tween.resume()
继续播放动画。一般再暂停后使用。等效与tween.paused(false)。

tween.reverse(from, suppressEvents)

反向播放动画。

from(Number或String): 开始反向播放的时间或位置。如果为指定，则从当前位置反向播放。设置0则从动画最后开始方向播放。也可以指定位置标签（String）。
suppressEvents(Boolean, 可选)：如果为true, 则当移动到播放位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值：Tween

例子：

tween.reverse();  //从当前位置反向播放
tween.reverse(2);  //从2秒的位置反向播放
tween.reverse(0);  //从动画结尾处反向播放
tween.reverse("-=1"); //从动画结尾前1秒的位置反向播放

tween.reversed(value)

获取或设置动画的反向播放状态。

value(Boolean): 指定反向播放状态。
返回值（Boolean或Tween）：如果不指定value参数，则返回反向状态，如果指定则返回Tween。

例子1：

tween.reversed(); //获取反向状态
tween.reversed(true); //设置反向状态为true

例子2：
若有一按钮，点击动画反向播放，再点击则正向播放，来回切换。

tween.reversed(!tween.reversed());

tween.seek(time, suppressEvents)

跳转到特定的时间，而不影响动画是否暂停或反向。

time(Number或String): 需要跳转到的特定的时间（Number），或需要跳转到的标签（在timeline中使用，这里不说明）。
suppressEvents(Boolean, 可选)：如果为true, 则当跳转到特定位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。

例子：

tween.seek(2); //跳转到2秒的位置
tween.seek(2, false); //跳转到2秒的位置，且触发相关回调

tween.startTime(value)

获取或设置动画在其父时间线上的开始时间（延迟之后）。

value(Number): 设置的开始时间，省略参数将返回当前的开始时间。
返回值（Number或Tween）：省略参数返回当前时间（Number），否则返回Tween。

例子1：

let tl = gsap.timeline();
let tween = gsap.to(".box", {
  duration: 2,
  delay: 3,
  y: 500
});
tl.add(tween);
tween.startTime(); //返回3

例子2：

let tl = gsap.timeline({
  delay: 2
});
let tween = gsap.to(".box", {
  duration: 2,
  delay: 3,
  y: 500
});
tl.add(tween);
tween.startTime(); //返回3

例子3：

let tl = gsap.timeline();
let tween = gsap.to(".box", {
  duration: 2,
  delay: 3,
  y: 500
});
tl.add(tween, 2);
tween.startTime(); //返回5

由上面例子1和2看来，startTime不包含父时间轴的延迟，但是由例子3看来，设置动画在父时间轴的位置却包含在内。这是因为，父时间轴延迟后才开始播放，而tween在父时间轴播放3秒后开始，所以startTime在父时间轴上是3秒时才开始。而将tween增加到2秒的位置，虽然和延迟2秒效果一样，但是这时父时间轴已经跑了2秒，加上tween的延迟，那么tween开始时间一共是在父时间轴播放后的第5秒。

tween.targets()

目标对象的数组。由创建动画时候gsap.to(targerts, vars)的targets参数决定。

tween.then(callback)

返回一个promise(参考JS的promise)。在tween或timeline结束后调用callback。和onComplete效果一样。

callback(Function): tween或timeline结束后调用。
返回值：Promise

例子：

gsap.to(".box", {
  duration: 2,
  y: 200
}).then(function(){
  console.log("complete");
})

tween.time(value)

获取或设置动画的当前时间。不包括任何的重复和延迟。

value(Number): 设置动画的时间。
返回值（Number或Tween）：如果指定参数value, 则返回Tween，否则返回当前时间。

例子1：
当动画运行过程中，tween.time()返回当前时间（0和2之间），不包含延迟或重复。当动画运行完后，tween.time()返回2。

let tween = gsap.to(".box", {
  delay: 3,
  duration: 2,
  y: 200,
  repeat: 5
});

例子2：
这里和tween.seek非常类似，但是他们的区别在于：seek是包含重复，如例子3。

tween.time(1); //播放头设置在1秒处，从此处开始播放

例子3：

let tween = gsap.to(".box", {
  duration: 2,
  y: 200,
  repeat: 5
});
tween.time(2); //运动5次
tween.time(10); //运动5次
tween.seek(10); //运动1次

该例子一共运动6次（1次+重复5次），每次开始的时间为0，2，4，6，8，10。tween.time不包含重复，参数只能是0和2（duration）之间。超过2则都按duration计算。所以从2秒开始动画都会重复5次。而seek是包含重复，所以seek从10秒开始就只是最后一次重复。

tween.timeScale(value)

获取或设置动画的播放速度。1为正常速度，2为双倍速度，0.5为半速播放。

value(Number): 播放速度。
返回值（Number或Tween）：不指定参数value，则返回当前播放速度。指定参数，则返回Tween。

例子：

tween.timeScale(); //返回当前播放速度
tween.timeScale(2); //设置2倍播放
tween.timeScale(0.5); //设置慢速播放

tween.totalDuration(value)

获取或设置动画的总时长。包括重复或重复延迟。

value(Number): 动画总时长。
返回值（Number或Tween）：不指定参数value，则返回当前时长。指定参数，则返回Tween。

例子1：
（原本一次动画时长 2）+（2次重复 22）+（ 2次重复延迟 1 2）= 8秒
可见是不包含delay。（因为动画在3秒后开始，并未计入时间轴）

let tween = gsap.to(".box", {
  delay: 3,
  duration: 2,
  y: 200,
  repeat: 2,
  repeatDelay: 1
});
tween.totalDuration(); //返回8秒

例子2：
继续例子1，将totalDuration设置4，缩短一半。动画的duration将会被压缩。

tween.totalDuration(4);

tween.totalProgress(value, suppressEvents)

获取或设置总进度。该值介于0和1之间。0在开始处，0.5播放一半，1播放完毕。

value(Number): 总进度值。
suppressEvents(Boolean, 可选)：如果为true, 则当跳转到特定位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值（Number或Tween）：不指定参数，则返回当前进度值。指定参数，则返回Tween。

例子1：
返回当前的总进度值。

tween.totalProgress();

例子2：
一共运动3次，totalProgress(0.5)运动了1次半。

let tween = gsap.to(".box", {
  duration: 2,
  y: 200,
  repeat: 2
});
tween.totalProgress(0.5);

tween.totalTime(time, suppressEvents)

获取或设置当前时间（播放头的位置），包含重复或重复延迟。

time(Number): 要设置的当前时间。
suppressEvents(Boolean, 可选)：如果为true, 则当跳转到特定位置时，不触发相关回调。若为false，则触发相关回调。默认值： true。
返回值（Number或Tween）：不指定参数value，则返回当前时间。指定参数，则返回Tween。

例子1：
播放完成后调用tween.totalTime()返回8，包含了重复和重复延迟。在动画过程中调用tween.totalTime()则返回0到8的中间值。

let tween = gsap.to(".box", {
  duration: 2,
  y: 200,
  repeat: 2,
  repeatDelay: 1
});

例子2：
总第5秒的位置播放。

tween.totalTime(5);

tween.yoyo(value)

获取或设置动画的yoyo状态，设置true，则动画将会往复运动，每次重复时交替。

value(Boolean): 需要设置的yoyo状态。
返回值（Boolean或Tween）：不指定参数value，则返回当前yoyo状态。指定参数，则返回Tween。

例子：
需配合repeat使用。

let tween = gsap.to(".box", {
  duration: 2,
  y: 200,
  repeat: 5,
  yoyo: true
});
tween.yoyo(); //返回yoyo状态
tween.yoyo(false); //设置yoyo状态

GSAP教程之tween.duration()和tween.totalDuration()的区别
 GSAP教程之tween.time()和tween.totalTime()的区别
 GSAP教程之tween.progress()和tween.totalProgres()的区别

GSAP教程之Tween详解

Tween属性详解

tween.data

tween.ratio (read-only)

tween.vars

Tween方法详解

tween.delay()

tween.duration()

tween.endTime()

tween.eventCallback()

tween.invalidate()

tween.isActive()

tween.iteration()

tween.kill()

tween.pause(atTime, suppressEvents)

tween.paused(value)

tween.play(from, suppressEvents)

tween.progress(value, suppressEvents)

tween.repeat(value)

tween.repeatDelay(value)

tween.restart(includeDelay, suppressEvents)

tween.reverse(from, suppressEvents)

tween.reversed(value)

tween.seek(time, suppressEvents)

tween.startTime(value)

tween.targets()

tween.then(callback)

tween.time(value)

tween.timeScale(value)

tween.totalDuration(value)

tween.totalProgress(value, suppressEvents)

tween.totalTime(time, suppressEvents)

tween.yoyo(value)

相关阅读

相关文章

相关问答

相关文档