Files
template/docs/render-guide/internals/animation-runner.md
T

32 KiB
Raw Blame History

动画执行器

动画执行器 Animater 实现 IAnimater,负责把多个动画对象的多个步骤组织成一条时间线。它关心的是「谁在第几步动、下一步什么时候开始」,而不是单个数值的平滑过渡;一个数从当前值靠近目标值,用渐变执行器。

前置知识

阅读本篇前,建议先读完:

获取执行器与激励接入

执行器自己不产生时间:它只接收外部传来的时间戳,再据此推进计划。推动它的对象叫激励源:例如 RafExcitation 每帧把当前时间戳推给执行器一次。没有接上激励源时,计划可以写好,但一步都不会执行。所以动手编排之前,先要知道执行器从哪里来、怎样接上时间。

组件内获取

组件里通常不自己创建执行器:手写 new 既要记得绑定激励源,又容易在组件卸载后继续持有。useAnimater(anim?, excitation?) 返回 IAnimater | null,只能在组件的 setup 或生命周期钩子中调用;它默认把执行器接到根渲染器的激励源上,根渲染器变化时重新绑定,组件卸载时解除绑定。

不传执行器时,它内部新建一个,并在卸载时一并销毁;传入已有执行器时,只负责绑定与解绑,执行器仍由调用方持有。需要显式指定激励源时,传第二个参数。使用 useAnimater 时,不需要自己调用 destroy()。

import { ref } from 'vue';
import { useAnimater } from '@motajs/render-vue';

const x = ref(0);

// 只能在组件 setup 或生命周期钩子中调用;
// 它绑定根渲染器的激励源,并在组件卸载时自动解绑。
const animater = useAnimater()!; // 尚无当前对象;尚无步骤;取得执行器

手动创建

不在组件里时,useAnimater 会返回 null,这时可以自己 new Animater()。它可以在普通 JavaScript 允许的任何位置创建;但执行器不会自己找时间,必须由你调用 bindExcitation(excitation) 把它接到一个数字激励源上。之后用 unbindExcitation() 解除绑定,也可以再接到别的源。

手动创建的执行器由调用方负责生命周期。需要停止并重置时调用 destroy():它会解绑激励源,并清掉已定义与正在执行的计划。这个清理是手动创建的场景才需要的;使用 useAnimater 时,卸载清理已经由它完成。

import { Animater, RafExcitation } from '@motajs/animate';

const excitation = new RafExcitation(); // 尚无当前对象;尚无步骤;创建激励源
// 可在普通 JS 中创建;执行器不会自己找时间。
const animater = new Animater(); // 尚无当前对象;尚无步骤;创建执行器

// 必须自己绑定激励源;不绑定就不会推进。
animater.bindExcitation(excitation); // 尚无当前对象;尚无步骤;绑定执行器自己的激励源

// 不再需要推进时解绑;之后可以重新绑定。
animater.unbindExcitation(); // 尚无当前对象;尚无步骤;解绑激励源

两种方式绑定的不是同一个激励源:useAnimater 默认绑根渲染器的激励源;new Animater 绑你传给 bindExcitation 的那个源。重复绑定同一个源不会重复登记。

计划模型

动画是某个可写数值从当前值走向目标值的一段过程。一次动画至少要回答三件事:哪个数值、走向哪个目标、用多久;曲线决定这段时间里快慢怎么变。

定义动画就是把这几项信息写进一条时间线:先确定动画对象,再确定曲线,然后写步骤。步骤只记录意图,不会立刻修改对象的数值;提交整组之前,数值保持原样。

每个步骤都有开始与结束两个时刻,后续步骤可以挂在其中一个时刻上,再等待若干毫秒。挂在开始时刻上的称为开始触发,挂在结束时刻上的称为结束触发;触发点上可以继续挂步骤,于是形成顺序、延迟与重叠。

  • 并行:同一组里没有挂到任何触发点上的步骤,会随组开始一起启动。
  • 顺序:把后一段挂到前一段的结束触发上;前一段结束、等待一段时间后,后一段才开始。
  • 延迟与重叠:把后一段挂到前一段的开始触发上;前一段开始、等待一段时间后,后一段就启动。结束触发等待 0 表示紧接着开始,开始触发等待 0 表示同时开始。
  • 计划组:一次提交的步骤集合是一组。组与组之间串行:后一组要等前一组的全部步骤、以及这些步骤上的触发点都结束,再经过组后等待,才真正开始。组内可以并行,组间不重叠。
  • 等待点:每个步骤结束时会兑现一个完成信号;也可以按组内编号查到某个步骤的目标值、时长、曲线和完成信号,再等待它。完成信号只代表这个步骤结束,不代表整组结束。

下面的 live 用真实执行器播放一组计划:上方是对象 A 与 B 的当前值,下方色块是步骤段,竖线是播放头。播放头本身也是一条同组同时长的步骤,不是页面定时器。

渲染示例需要浏览器环境。

动画对象的选择

为了让动画系统知道它该如何执行动画、将当前值写入哪个对象,就必须先使用 animate 接口来绑定动画对象。animate(content: IAnimatable): this 选中的对象必须满足 IAnimatable:一个带可写 value 的对象;Vue 的 ref<number> 就满足这个形状。执行器只改这个字段,不负责把值画到画布。

animate 只改变「之后的操作作用在谁身上」,本身不新增步骤,也不移动任何值。同一个对象在一个计划组里可以多次出现,它的步骤编号会继续累加。没有先选对象就调用 to 时,执行器不会添加任何步骤——计划看起来写了,实际不会动,所以选择对象要放在写步骤之前。

import { ref } from 'vue';
import { useAnimater } from '@motajs/render-vue';

const x = ref(0);
const animater = useAnimater()!;

animater.animate(x); // 当前对象:x;尚无步骤;选择 x 作为动画对象

曲线

一条步骤只知道从当前值走向目标值、用多久;如果不再说明过程中的快慢,系统只能用匀速。curve(curve: ExcitationCurve): this 就是为此设置速率曲线的。ExcitationCurve 是 (progress: number) => number,把 0–1 的时间进度映射成一个数;不设置时使用线性曲线。

时间进度从 0 走到 1。曲线在当前进度下的返回值表示此时刻动画的完成度:为 0 时动画处于起点,为 1 时刚好执行到目标值,中间按曲线返回的比例推进。曲线返回值超出 0 到 1 时,值会越过目标或朝反方向走。

曲线在定义步骤时记入步骤,之后再改 curve 不会影响已经定义好的步骤。它会一直作用于后续步骤,直到再次调用 curve;planEnd 不会把它恢复成线性。

import { sin } from '@motajs/animate';

const x = ref(0);

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(sin()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 400) // 当前对象:x;新增索引 1;写入步骤
    .planEnd(); // 当前对象:x;索引 1;结束本组,当前对象清空

步骤与终值

计划模型与选好的对象还只是准备,要真正让某个值动起来,必须追加一条具体步骤:从当前值走到哪个目标值、用多久。to(value: number, time: number, end: EndRelation = EndRelation.Target): this 就是用来追加这条步骤的。不调用 to,再完整的模型也不会产生动画。

value 是目标值,time 是时长(毫秒),end 是结束参考方式。调用 to 只把步骤写进当前组,不会立刻修改动画对象的值;要等组开始并执行到这一步时才生效。如果当前正挂着开始触发或结束触发,这条步骤会挂到触发点,而不是随组开始;没有触发点时,它才是组启动步骤。

EndRelation 决定动画结束时把值写成什么:

结尾参考 动画结束时的值
EndRelation.Target 直接写成传入的目标值
EndRelation.Curve 停在曲线终点;不一定等于目标值
EndRelation.Self 正常结束时同 Curve;提前结束时停在接管那一刻的值

默认是 EndRelation.Target。使用 Curve 时,如果曲线在终点不回到目标值,对象最终会停在另一个值;终点由曲线在 1 处的输出决定。

import { sin } from '@motajs/animate';

const x = ref(0);

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(sin()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(100, 400, EndRelation.Curve) // 当前对象:x;新增索引 1;写入步骤,结尾按曲线终点
    .planEnd(); // 当前对象:x;索引 1;结束本组,当前对象清空

结束触发

组内步骤默认一起开始;如果希望后一段等前一段真正结束再开始,就需要把后一段挂到前一段的结束时刻上。after(time = 0): this 做这件事:它把后续步骤挂到上一次定义的步骤结束之后,再等待 time 毫秒。没有它,两段只能并行,或者靠猜时长来凑先后。

after 锚定的是上一次定义的步骤,不是当前 animate 选中的对象;如果还没有任何步骤,它不会建立关联。把 after 直接写在它要锚定的 to 后面,再选下一个对象,读起来就是「这段结束后,再让谁动」:

const x = ref(0);
const y = ref(0);

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(1, 400) // 当前对象:x;新增索引 1;写入步骤
    .after(120) // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后,等待 120ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(1, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

after 只能锚定上一条定义的步骤;要挂在组里其它对象、其它编号的步骤之后,就需要按对象与编号指定。afterPlan(content: IAnimatable, index: number, time = 0): this 就是为此把后续步骤挂到当前计划组里指定对象、指定索引的步骤结束之后。index 从 1 开始;找不到对应步骤时不会建立这个关联,若之前已经挂过触发,基准保持原样,否则后续步骤随组开始。

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(100, 200) // 当前对象:x;新增索引 1;写入步骤
    .afterPlan(x, 1, 50) // 当前对象:x;索引 1;把后续步骤挂到 x 索引 1 结束之后,等待 50ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(50, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

调用 after 或 afterPlan 之后,后续的步骤会继续挂到同一个基准上,直到下一次 after、when 或 planEnd 改变它。两者都只能引用当前正在定义的组;已经封口的组不能再被挂触发点。

开始触发

结束触发只能让两段首尾相接;若希望后一段在前一段开始后某个时刻就启动,让两段重叠,就需要以开始时刻为基准。when(time = 0): this 把后续步骤挂到上一次定义的步骤开始时刻之后,再等待 time 毫秒。没有它,两段要么完全同时开始,要么等前一段结束。

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(1, 400) // 当前对象:x;新增索引 1;写入步骤
    .when(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 100ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(1, 150) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

when 也只能锚定上一条定义的步骤;要以后面组里任意一条已有步骤的开始时刻为基准,就需要按对象与编号指定。whenPlan(content: IAnimatable, index: number, time = 0): this 就是为此以当前计划组里指定对象、指定索引的步骤为基准,从它开始执行的时刻起等待 time 毫秒。写法与 afterPlan 相同,只是基准从「步骤结束」改为「步骤开始」。

animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(1, 500) // 当前对象:x;新增索引 1;写入步骤
    .whenPlan(x, 1, 200) // 当前对象:x;索引 1;把后续步骤挂到 x 索引 1 开始之后,等待 200ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(1, 200) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

when 与 after 都锚定上一次定义的步骤,所以调用顺序会影响挂载点:先 animate(y) 不会改变锚点,紧接着的 when 或 after 仍然挂在 x 的上一条步骤上。把触发写在锚点步骤之后,可以少一次回头确认。

查询与等待

计划提交后,代码有时需要读出某一步的目标值与时长。query(content: IAnimatable, index: number, plan?: number): IAnimationPlan | null 就是为此查询步骤的;没有它,只能自己记住定义时写了什么,或者等整组结束后再回头找。

另一些时候,代码只想等某一步完成再继续,而不想等整组结束。wait(content: IAnimatable, index: number, plan?: number): Promise<void> 就是为此等待单个步骤的;没有它,只能猜时长,或者在组尾统一处理。

index 是该对象在本计划组里的步骤编号,从 1 开始;plan 是计划组索引,由 planEnd 返回。省略 plan 时,query 查询当前正在定义中的组;planEnd 之后当前组已经封口,要查已定义的组必须显式传入组索引。wait 省略 plan 时先找当前正在执行的组;没有执行中的组时,按当前正在定义中的组查找。步骤不存在时立即兑现,步骤存在时只等这一条结束,不等整组。步骤被后续步骤接管时,它的完成信号也会兑现。

IAnimationPlan 的常用成员:

成员 含义
identifier 动画对象与组内步骤编号
curve 这个步骤的速率曲线
targetValue 目标值
time 动画时长
promise 这个步骤执行完毕后兑现的 Promise
const x = ref(0);

const group = animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(100, 300) // 当前对象:x;新增索引 1;写入步骤
    .after(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后,等待 100ms
    .to(200, 200) // 当前对象:x;新增索引 2;写入步骤(挂到索引 1 结束之后)
    .planEnd(); // 当前对象:x;索引 2;结束本组,当前对象清空

const second = animater.query(x, 2, group); // 当前对象:无;组 group 索引 2;读取 x 的步骤
// second?.targetValue 为 200

await animater.wait(x, 2, group); // 当前对象:无;组 group 索引 2;等待 x

query 与 wait 的默认范围不同:query 默认查当前正在定义的组,wait 默认查当前正在执行的组。定义完计划后要查询该组,通常显式传入 planEnd 的返回值。

计划组收尾

写步骤时,系统需要一个明确边界知道「这一组到这里定义完毕」,并据此决定什么时候开始执行、组前与组后各等多久、下一组怎样排队;planEnd(preTime = 0, postTime = 0): number 就是这条边界。不调用它,当前组不会提交,后续步骤会继续累积在同一组里,也不会开始执行。

planEnd 什么时候调用由你决定:在关闭它之前,当前组一直保持「定义中」,可以继续用 to 往里加步骤。它不需要在写完第一条步骤后立刻调用;但组只有在 planEnd 之后才会被排队执行。

planEnd 返回组索引,从 1 开始;没有定义任何步骤时返回 -1。

  • preTime 是组执行前的等待时长(毫秒),等待结束后才开始组内第一批步骤。
  • postTime 是组执行后的等待时长(毫秒),组内步骤、开始触发与结束触发全部结束后再等待这么久,计划组才真正结束。
  • 后一个计划组会等前一个计划组全部结束之后才开始,因此组与组之间不会重叠。
const x = ref(0);
const y = ref(0);

// 第一个计划组:x 与 y 同时走向各自目标
animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .to(100, 300) // 当前对象:x;新增索引 1;写入步骤
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(50, 300) // 当前对象:y;新增索引 1;写入步骤(随组开始,与 x 并行)
    .planEnd(); // 当前对象:y;索引 1;结束组 1,当前对象清空

// 第二个计划组:等第一个组全部结束后,x 再回到 0
animater
    .animate(x) // 当前对象:x;新组重新计数,尚无步骤;选择 x
    .to(0, 200) // 当前对象:x;新增索引 1;写入步骤
    .planEnd(); // 当前对象:x;索引 1;结束组 2,当前对象清空

执行器状态与读取规则

把上面的操作放在一起看,Animater 是一台按状态工作的执行器:它记住当前选中的对象、当前曲线、触发基准,以及正在定义或执行的计划组。每个接口只读写其中一部分状态;理解这一点,才能判断一行代码在看谁、写谁。

操作 读取的状态 改变的状态
animate(content) 无 当前对象,以及该对象的步骤容器
curve(curve) 无 当前曲线,供后续 to 记录
to(value, time, end) 当前对象、当前曲线、当前触发基准 向当前计划组写入一条步骤,步骤编号加一
after(time) / when(time) 上一个定义的步骤 触发基准与等待时长
afterPlan(...) / whenPlan(...) 当前计划组中指定对象、指定编号的步骤 触发基准与等待时长
planEnd(...) 当前计划组 关闭并排队该组,返回组编号
query(...) 默认读取当前正在定义的组 无
wait(...) 默认读取当前正在执行的组;没有时读正在定义的组 无
destroy() 无 解绑激励源,清空计划与执行状态

其中最容易看错的是 to:它同时依赖选中的对象、当前曲线与当前触发基准。没有先用 animate 选中对象时,to 不写入任何步骤,计划看起来写了,实际不会动。

after 与 when 改的是触发基准,不是当前对象。之后即使换了对象,基准也会保持,直到下一次触发设置或 planEnd。

query 与 wait 的默认范围不同:query 默认读当前正在定义的组;wait 默认读当前正在执行的组,没有执行中的组时读当前正在定义的组。

组合与编排示例

下面每个示例前都先说明它表示的动画;示例里的 x、y 是已经声明好的动画对象,animater 由 useAnimater() 取得,linear() 来自 @motajs/animate。每个示例后配两个 live:一个看时间轴,一个看数值播放;两者都由真实执行器推进。

顺序执行

这个示例表示:x 先走完,y 才开始。

// x 走完,y 才开始
animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 700) // 当前对象:x;新增索引 1;写入步骤
    .after() // 当前对象:x;索引 1;把后续步骤挂到索引 1 结束之后
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(1, 450) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 结束之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

after() 不等待额外时间,所以 y 在 x 结束的同一刻启动。

时间轴视图:色块是步骤段,竖线是播放头。

渲染示例需要浏览器环境。

播放视图:两个圆点分别表示 x 与 y 的当前值。

渲染示例需要浏览器环境。

并行执行

这个示例表示:x 与 y 同时开始,各自走向自己的目标。

// x、y 同时开始,各自走向自己的目标
animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 900) // 当前对象:x;新增索引 1;写入步骤(随组开始)
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线
    .to(0.5, 900) // 当前对象:y;新增索引 1;写入步骤(随组开始,与 x 并行)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

两条步骤都没有挂触发点,所以都会随组开始;它们只共享开始时刻,不共享目标、时长或曲线。

时间轴视图:两条步骤段从同一刻开始。

渲染示例需要浏览器环境。

播放视图:两个值同时变化。

渲染示例需要浏览器环境。

延迟与重叠

这个示例表示:x 先开始,y 在 x 开始 300ms 后启动,两者重叠 600ms。

// x 先走 1000ms,y 在 x 开始 300ms 后启动,两者重叠 600ms
animater
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 1000) // 当前对象:x;新增索引 1;写入步骤
    .when(300) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 300ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .to(1, 600) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

when(300) 以 x 的开始为基准,所以 y 在 x 走了 300ms 时启动,而不是等 x 结束。

时间轴视图:y 的步骤段从 x 中段开始。

渲染示例需要浏览器环境。

播放视图:x 先动,y 稍后启动。

渲染示例需要浏览器环境。

两个计划组

这个示例表示:组 1 的 x 全部结束后,组 2 的 y 才开始;组间不需要额外写等待。

// 组 2 会等组 1 全部结束;不需要额外写等待
const first = animater // 当前对象:无;尚无步骤;开始定义组 1
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 600) // 当前对象:x;新增索引 1;写入步骤
    .planEnd(); // 当前对象:x;索引 1;结束组 1,当前对象清空

const second = animater // 当前对象:无;新组;开始定义组 2
    .animate(y) // 当前对象:y;新组重新计数,尚无步骤;选择 y
    .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线
    .to(1, 600) // 当前对象:y;新增索引 1;写入步骤
    .planEnd(); // 当前对象:y;索引 1;结束组 2,当前对象清空

// 等组 1 的 x 步骤,或等组 2 的 y 步骤,都可以
await animater.wait(x, 1, first); // 当前对象:无;组 first 索引 1;等待 x
await animater.wait(y, 1, second); // 当前对象:无;组 second 索引 1;等待 y

时间轴视图:两组首尾相接,中间没有重叠。

渲染示例需要浏览器环境。

播放视图:x 完成后,y 才从 0 开始。

渲染示例需要浏览器环境。

查询与等待指定步骤

这个示例表示:先读出 y 这条步骤的目标与时长,再只等待 y 结束。

const group = animater // 当前对象:无;尚无步骤;开始定义一组
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 300) // 当前对象:x;新增索引 1;写入步骤
    .when(100) // 当前对象:x;索引 1;把后续步骤挂到索引 1 开始之后,等待 100ms
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线
    .to(1, 200) // 当前对象:y;新增索引 1;写入步骤(挂到 x 索引 1 开始之后)
    .planEnd(); // 当前对象:y;索引 1;结束本组,当前对象清空

const yStep = animater.query(y, 1, group); // 当前对象:无;组 group 索引 1;读取 y 的步骤
// yStep?.targetValue 为 1,yStep?.time 为 200

// 只等 y 这一条步骤,不等待整组
await animater.wait(y, 1, group); // 当前对象:无;组 group 索引 1;等待 y

这里的 query 与 wait 都显式传入了 planEnd 返回的组索引,所以查的是已封口的组,而不是之后还在定义的组。

时间轴视图:x 与 y 重叠,等待只针对 y 那一段。

渲染示例需要浏览器环境。

播放视图:先显示查到的 y 目标与时长,再播放数值。

渲染示例需要浏览器环境。

中途改道

这个示例表示:x 的第一段走到 700ms 时被第二段接管,改为走回 0;y 仍按自己的节奏走完。

const group = animater // 当前对象:无;尚无步骤;开始定义一组
    .animate(x) // 当前对象:x;尚无步骤;选择 x
    .curve(linear()) // 当前对象:x;尚无步骤;设置当前曲线
    .to(1, 1200, EndRelation.Self) // 当前对象:x;新增索引 1;写入步骤,结尾保留改道时的值
    .animate(y) // 当前对象:y;尚无步骤;选择 y
    .curve(linear()) // 当前对象:y;尚无步骤;设置当前曲线
    .to(1, 1500) // 当前对象:y;新增索引 1;写入步骤
    .whenPlan(x, 1, 700) // 当前对象:y;索引 1;把触发基准改为 x 索引 1 开始后 700ms
    .animate(x) // 当前对象:x;已有索引 1;重新选择 x
    .curve(linear()) // 当前对象:x;已有索引 1;设置当前曲线
    .to(0, 500) // 当前对象:x;新增索引 2;写入步骤(挂到 x 索引 1 开始后 700ms)
    .planEnd(); // 当前对象:x;索引 2;结束本组,当前对象清空

await animater.wait(x, 1, group); // 当前对象:无;组 group 索引 1;等待 x 第 1 段(改道时兑现)
await animater.wait(x, 2, group); // 当前对象:无;组 group 索引 2;等待 x 第 2 段

第一段使用 EndRelation.Self,接管时会停在改道时刻的值;如果使用默认的 Target,它会先跳到原来的目标值,再被新步骤拉回。被接管的那一段不会触发它挂的结束触发点。

时间轴视图:x 的第一段在 700ms 处截断,第二段从那里接上。

渲染示例需要浏览器环境。

播放视图:x 在改道后从当前值走回 0,y 继续走完。

渲染示例需要浏览器环境。

与渐变执行器的分工

Animater 负责多个对象、多个步骤的编排;只是让单个数值连续靠近目标值时,用渐变执行器。

边界与注意

  • 同一个对象在同一时刻只能开始一条步骤:两条步骤同时启动会报错并跳过后一条;启动时刻更晚时,前一条会立刻结束再开始新的。
  • after 与 when 锚定上一次定义的步骤,与当前 animate 选中的对象无关;中间换了对象,锚点也不会跟着换。
  • 被接管的那一段不会触发它挂的结束触发点;需要停在接管时刻的值时用 EndRelation.Self,默认的 Target 会先跳到原目标值再被拉回。
<script setup> import RenderDemo from '../../.vitepress/components/renderDemo.vue'; const timelineLoader = () => import('../../.vitepress/components/demos/ui/animater-timeline.tsx'); const sequentialTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-sequential-timeline.tsx'); const sequentialPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-sequential-playback.tsx'); const parallelTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-parallel-timeline.tsx'); const parallelPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-parallel-playback.tsx'); const delayedTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-delayed-timeline.tsx'); const delayedPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-delayed-playback.tsx'); const relayTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-relay-timeline.tsx'); const relayPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-relay-playback.tsx'); const queryTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-query-timeline.tsx'); const queryPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-query-playback.tsx'); const retargetTimelineLoader = () => import('../../.vitepress/components/demos/ui/animater-retarget-timeline.tsx'); const retargetPlaybackLoader = () => import('../../.vitepress/components/demos/ui/animater-retarget-playback.tsx'); </script>