three.js AnimationAction

AnimationActions 用來(lái)調(diào)度存儲(chǔ)在AnimationClips中的動(dòng)畫(huà)。

說(shuō)明: AnimationAction的大多數(shù)方法都可以鏈?zhǔn)秸{(diào)用

在使用手冊(cè)的“下一步”章節(jié)中，“動(dòng)畫(huà)系統(tǒng)”一文對(duì)three.js動(dòng)畫(huà)系統(tǒng)中的不同元素作出了概述。

構(gòu)造器

AnimationAction( mixer : AnimationMixer, clip : AnimationClip, localRoot : Object3D )

mixer - 被此動(dòng)作控制的 *動(dòng)畫(huà)混合器*

clip - *動(dòng)畫(huà)剪輯* 保存了此動(dòng)作當(dāng)中的動(dòng)畫(huà)數(shù)據(jù)

localRoot - 動(dòng)作執(zhí)行的根對(duì)象

說(shuō)明: 不要直接調(diào)用這個(gè)構(gòu)造函數(shù)，而應(yīng)該先用AnimationMixer.clipAction實(shí)例化一個(gè)AnimationAction，因?yàn)檫@個(gè)方法提供了緩存以提高性能。

屬性

.clampWhenFinished : Boolean

如果 clampWhenFinished 值設(shè)為true, 那么動(dòng)畫(huà)將在最后一幀之后自動(dòng)暫停（paused）

如果 clampWhenFinished 值為false, enabled 屬性值將在動(dòng)作的最后一次循環(huán)完成之后自動(dòng)改為false, 那么這個(gè)動(dòng)作以后就不會(huì)再執(zhí)行。

默認(rèn)值為false

說(shuō)明: 動(dòng)作如果被中斷了，clampWhenFinished將無(wú)效 (只有當(dāng)最后一次循環(huán)執(zhí)行完畢之后才能起效）

.enabled : Boolean

enabled 值設(shè)為false會(huì)禁用動(dòng)作, 也就是無(wú)效.默認(rèn)值是true

當(dāng)enabled被重新置為true, 動(dòng)畫(huà)將從當(dāng)前時(shí)間（time）繼續(xù) (將 enabled 置為 false 不會(huì)重置此次動(dòng)作)

說(shuō)明: 將enabled置為true不會(huì)讓動(dòng)畫(huà)自動(dòng)重新開(kāi)始。只有滿足以下條件時(shí)才會(huì)馬上重新開(kāi)始: 暫停（paused）值為false, 同時(shí)動(dòng)作沒(méi)有失效 (執(zhí)行停止(stop)命令或重置(reset)命令， 且權(quán)重(weight)和時(shí)間比例(timeScale)都不能為0

.loop : Number

循環(huán)模式 (可以通過(guò)setLoop改變)。默認(rèn)值是 THREE.LoopRepeat (重復(fù)repetitions次數(shù)無(wú)窮)

必須是以下值之一：

THREE.LoopOnce - 只執(zhí)行一次
THREE.LoopRepeat - 重復(fù)次數(shù)為repetitions的值, 且每次循環(huán)結(jié)束時(shí)候?qū)⒒氐狡鹗紕?dòng)作開(kāi)始下一次循環(huán)。
THREE.LoopPingPong - 重復(fù)次數(shù)為repetitions的值, 且像乒乓球一樣在起始點(diǎn)與結(jié)束點(diǎn)之間來(lái)回循環(huán)。

.paused : Boolean

paused置為true會(huì)通過(guò)將動(dòng)作的有效時(shí)間比例改為0來(lái)使動(dòng)作暫停執(zhí)行。默認(rèn)值是false

.repetitions : Number

整個(gè)動(dòng)作過(guò)程動(dòng)畫(huà)剪輯（AnimationClip）執(zhí)行的次數(shù)，可以通過(guò)setLoop修改。默認(rèn)值是Infinity

如果循環(huán)模式（loop mode）值被設(shè)置為T(mén)HREE.LoopOnce，repetitions值將會(huì)無(wú)效。

.time : Number

動(dòng)作開(kāi)始的時(shí)間點(diǎn) (單位是秒, 從0開(kāi)始計(jì)時(shí)).

這個(gè)值被限定在 0到clip.duration(根據(jù)循環(huán)狀態(tài))范圍之內(nèi). 可以通過(guò)改變時(shí)間比例（timeScale) (使用 setEffectiveTimeScale 或者 setDuration)來(lái)將它相對(duì)于全局的混合器縮放.

.timeScale : Number

時(shí)間(time)的比例因子. 值為0時(shí)會(huì)使動(dòng)畫(huà)暫停。值為負(fù)數(shù)時(shí)動(dòng)畫(huà)會(huì)反向執(zhí)行。默認(rèn)值是1。

關(guān)于timeScale屬性/方法 (不同于 time) 有: getEffectiveTimeScale, halt, paused, setDuration, setEffectiveTimeScale, stopWarping, syncWith, warp.

.weight : Number

動(dòng)作的影響程度 (取值范圍[0, 1]). 0 (無(wú)影響)到1（完全影響）之間的值可以用來(lái)混合多個(gè)動(dòng)作。默認(rèn)值是1

關(guān)于weight的屬性/方法有: crossFadeFrom, crossFadeTo, enabled, fadeIn, fadeOut, getEffectiveWeight, setEffectiveWeight, stopFading.

.zeroSlopeAtEnd : Boolean

啟用平滑插值，無(wú)須單獨(dú)剪輯開(kāi)始、循環(huán)和結(jié)束。默認(rèn)值是true

.zeroSlopeAtStart : Boolean

啟用平滑插值，無(wú)須單獨(dú)剪輯開(kāi)始、循環(huán)和結(jié)束。默認(rèn)值是true

方法

.crossFadeFrom ( fadeOutAction : AnimationAction, durationInSeconds : Number, warpBoolean : Boolean ) : this

在傳入的時(shí)間段內(nèi)，讓此動(dòng)作淡入(fade in),同時(shí)讓另一個(gè)動(dòng)作淡出。此方法可鏈?zhǔn)秸{(diào)用。

如果warpBoolean值是true, 額外的 warping (時(shí)間比例的漸變)將會(huì)被應(yīng)用。

說(shuō)明: 與 fadeIn/fadeOut一樣, 淡入淡出動(dòng)作開(kāi)始/結(jié)束時(shí)的權(quán)重是1.

.crossFadeTo ( fadeInAction : AnimationAction, durationInSeconds : Number, warpBoolean : Boolean ) : this

在傳入的時(shí)間段內(nèi), 讓此動(dòng)作淡出（fade out），同時(shí)讓另一個(gè)動(dòng)作淡入。此方法可鏈?zhǔn)秸{(diào)用。

如果warpBoolean值是true, 額外的 warping (時(shí)間比例的漸變)將會(huì)被應(yīng)用。

說(shuō)明: 與 fadeIn/fadeOut一樣, 淡入淡出動(dòng)作開(kāi)始/結(jié)束時(shí)的權(quán)重是1.

.fadeIn ( durationInSeconds : Number ) : this

在傳入的時(shí)間間隔內(nèi)，逐漸將此動(dòng)作的權(quán)重（weight）由0升到1。此方法可鏈?zhǔn)秸{(diào)用。

.fadeOut ( durationInSeconds : Number ) : this

在傳入的時(shí)間間隔內(nèi)，逐漸將此動(dòng)作的權(quán)重（weight）由1降至0。此方法可鏈?zhǔn)秸{(diào)用。

.getEffectiveTimeScale () : Number

返回有效時(shí)間比例(考慮當(dāng)前的變形狀態(tài)和paused值).

.getEffectiveWeight () : number

返回影響權(quán)重(考慮當(dāng)前淡入淡出狀態(tài)和enabled的值).

.getClip () : AnimationClip

返回存有此動(dòng)作的動(dòng)畫(huà)數(shù)據(jù)的剪輯

.getMixer () : AnimationMixer

返回負(fù)責(zé)完成此動(dòng)作的混合器

.getRoot () : Object3D

返回執(zhí)行此動(dòng)作的根對(duì)象

.halt ( durationInSeconds : Number ) : this

在傳入的時(shí)間間隔內(nèi)，通過(guò)從當(dāng)前值開(kāi)始逐漸降低時(shí)間比例(timeScale)使動(dòng)畫(huà)逐漸減速至0。此方法可鏈?zhǔn)秸{(diào)用。

.isRunning () : Boolean

返回當(dāng)前此動(dòng)作的時(shí)間(time)是否正在流逝除了在混合器中被激活之外 (參見(jiàn)isScheduled)必須滿足以下條件才會(huì)返回true: paused值等于false, enabled值為true, timeScale值不為0, 而且沒(méi)有安排延時(shí)啟動(dòng)(startAt).說(shuō)明 isRunning 為true并不意味著此動(dòng)畫(huà)一定會(huì)切實(shí)地被看到。僅當(dāng)權(quán)重(weight)被設(shè)置為非零值時(shí)才是這種情況。

.isScheduled () : Boolean

如果動(dòng)作是在混合器中被激活的，返回true。說(shuō)明: 這并不意味著動(dòng)畫(huà)正在執(zhí)行中 (需要額外判斷isRunning值)

.play () : this

讓混合器激活動(dòng)作。此方法可鏈?zhǔn)秸{(diào)用。說(shuō)明: 激活動(dòng)作并不意味著動(dòng)畫(huà)會(huì)立刻開(kāi)始: 如果動(dòng)作在此之前已經(jīng)完成（到達(dá)最后一次循環(huán)的結(jié)尾），或者如果已經(jīng)設(shè)置了延時(shí) 啟動(dòng)(通過(guò) startAt)，則必須先執(zhí)行重置操作（reset）。 一些其它的設(shè)置項(xiàng) (paused=true, enabled=false, weight=0, timeScale=0) 也可以阻止動(dòng)畫(huà)的開(kāi)始。

.reset () : this

重置動(dòng)作。此方法可鏈?zhǔn)秸{(diào)用。該方法會(huì)將暫停值 paused 設(shè)為false, 啟用值enabled 設(shè)為true,時(shí)間值 time設(shè)為0, 中斷任何預(yù)定的淡入淡出和變形, 以及移除內(nèi)部循環(huán)次數(shù)以及延遲啟動(dòng)。說(shuō)明: 停止方法stop內(nèi)調(diào)用了重置方法（reset）, 但是 .reset不會(huì)調(diào)用 .stop。 這就表示: 如果你想要這兩者, 重置并且停止, 不要調(diào)用reset; 而應(yīng)該調(diào)用stop。

.setDuration ( durationInSeconds : Number ) : this

設(shè)置單此循環(huán)的持續(xù)時(shí)間(通過(guò)調(diào)整時(shí)間比例（timeScale）以及停用所有的變形)。此方法可以鏈?zhǔn)秸{(diào)用。

.setEffectiveTimeScale ( timeScale : Number ) : this

設(shè)置時(shí)間比例（timeScale）以及停用所有的變形)。 此方法可以鏈?zhǔn)秸{(diào)用。如果暫停 （paused）值為false, 有效的時(shí)間比例(一個(gè)內(nèi)部屬性) 也會(huì)被設(shè)為該值; 否則有效時(shí)間比例 (直接影響當(dāng)前動(dòng)畫(huà) 將會(huì)被設(shè)為0.說(shuō)明: 如果時(shí)間比例.timeScale 被此方法設(shè)為0，暫停值paused不會(huì)被自動(dòng)改為true。

.setEffectiveWeight ( weight : Number ) : this

設(shè)置權(quán)重（weight）以及停止所有淡入淡出。該方法可以鏈?zhǔn)秸{(diào)用。如果啟用屬性（enabled）為true, 那么有效權(quán)重(一個(gè)內(nèi)部屬性) 也會(huì)被設(shè)為該值; 否則有效權(quán)重 (直接影響當(dāng)前動(dòng)畫(huà))將會(huì)被設(shè)為0.說(shuō)明: 如果該方法將權(quán)重weight值設(shè)為0，啟用值enabled不會(huì)被自動(dòng)改為false。

.setLoop ( loopMode : Number, repetitions : Number ) : this

設(shè)置循環(huán)（loop mode）及循環(huán)重復(fù)次數(shù)（repetitions）。改方法可被鏈?zhǔn)秸{(diào)用。

.startAt ( startTimeInSeconds : Number ) : this

定義延時(shí)啟動(dòng)的事件 (通常會(huì)傳入AnimationMixer.time + deltaTimeInSeconds)。 該方法可以鏈?zhǔn)秸{(diào)用。說(shuō)明: 如果 startAt方法是和play方法一起鏈?zhǔn)秸{(diào)用, 或者動(dòng)畫(huà)已經(jīng)在混合器中被激活 (通過(guò)先行調(diào)用play, 同時(shí)沒(méi)有停止或重置)，動(dòng)畫(huà)將僅在給定時(shí)間開(kāi)始.

.stop () : this

讓混合器停止動(dòng)作。該方法可以被鏈?zhǔn)秸{(diào)用。動(dòng)作會(huì)馬上停止以及完全[page:.reset 重置].說(shuō)明: 你可以通過(guò)mixer.stopAllAction在一個(gè)混合器中一舉停止所有處于激活態(tài)的動(dòng)作。

.stopFading () : this

停止動(dòng)作中所有預(yù)定的淡入淡出（fading）。該方法可以被鏈?zhǔn)秸{(diào)用。

.stopWarping () : this

停用動(dòng)作中所有預(yù)定的變形warping。該方法可被鏈?zhǔn)秸{(diào)用。

.syncWith ( otherAction : AnimationAction ) : this

將此動(dòng)作與傳入的其它動(dòng)作同步。此方法可被鏈?zhǔn)秸{(diào)用。同步是通過(guò)將動(dòng)作的時(shí)間(time)或時(shí)間比例(timeScale)與另一動(dòng)作設(shè)置一致來(lái)實(shí)現(xiàn)的 (停用所有預(yù)定的變形)。說(shuō)明: 另一動(dòng)作的 time 和 timeScale未來(lái)變化將不會(huì)被檢測(cè)到.

.warp ( startTimeScale : Number, endTimeScale : Number, durationInSeconds : Number ) : this

在傳入的事件間隔內(nèi)，通過(guò)逐漸將時(shí)間比例timeScale由startTimeScale修改至endTimeScale來(lái)改變回放速度。該方法可被鏈?zhǔn)秸{(diào)用。

事件

有兩個(gè)事件分別表示了單次循環(huán)的結(jié)束和全部動(dòng)作的結(jié)束，你可以這樣對(duì)它們做出響應(yīng):

mixer.addEventListener( 'loop', function( e ) { …} ); // properties of e: type, action and loopDelta
mixer.addEventListener( 'finished', function( e ) { …} ); // properties of e: type, action and direction

源碼

src/animation/AnimationAction.js