GSAP教程之Tween详解

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 tweenconsole.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()的区别