docs: 完成动画文档与编写流程

This commit is contained in:
AncTe committed 2026-11-20 14:23:11 +08:00
1 parent ab09cf1990
commit b194d58c16
76 files changed
+11718 -26

No files matched your search

+389
View File
@@ -0,0 +1,389 @@
# 动画
动画就是一系列数据按照指定方式变化:位置、透明度、颜色与进度条长度,都可以随时间连续改变。曲线决定「时间从起点走到终点时,数据按什么方式变化」;把数据与曲线交给动画系统,值就会平滑过渡,而不是瞬间跳过去。
本篇先讲曲线如何把时间映射成数据,再按基础、缓动与双曲三组介绍内置曲线的参数与形状,最后讲三个高层接口 `transitioned`、`transitionedColor` 与 `cycledTransition`。更底层的执行器与激励源见渲染底层。
## 前置知识
阅读本篇前,建议先读完:
- [响应式](./reactivity.md)
- [UI 入门](../basics/ui-basics.md)
## 动画的本质与曲线
一个动画由两部分组成:一份要变化的数据,和一条把时间进度映射成数据取值的曲线。时间进度通常叫 `progress`,从 `0`(开始)走到 `1`(结束)。曲线接收 `progress`,返回一个数;动画系统按这个返回值,在起始值与目标值之间取出当前值。
```ts
type ExcitationCurve = (progress: number) => number;
```
`progress` 在 `0` 到 `1` 之间,曲线的输出不要求也落在 `0` 到 `1`:输出可以超出这个范围,所以过程中可以低于起始值或高于目标值,也可以多次起伏。曲线只决定过渡过程,不决定动画最终落在哪个值;最终落点由使用曲线的动画接口给出。
内置曲线都从 `@motajs/animate` 导入。不带 `mode` 参数的曲线直接返回一条固定形状的曲线;带 `mode` 参数的曲线会在内部套用下面的曲线模式。
## 曲线模式
曲线本身只保证「缓进快出」这一种基本形状。给它套一个 `CurveMode`,就能改变快慢分布。`CurveMode` 是曲线的模式枚举,默认 `CurveMode.EaseIn`。
| 模式 | 含义 | 形状 |
| ---------------------- | ---------------- | ------------------------------ |
| `CurveMode.EaseIn` | 缓进快出 | 从起点慢慢加速,越接近终点越快 |
| `CurveMode.EaseOut` | 快进缓出 | 起步快,接近终点逐渐减速 |
| `CurveMode.EaseInOut` | 缓进缓出,中间快 | 两端慢、中段最快 |
| `CurveMode.EaseCenter` | 快进快出,中间缓 | 两端快、中段最慢 |
这四种模式都从 `0` 开始、到 `1` 结束,区别只在过程中的快慢分布:`EaseIn` 越走越快,`EaseOut` 越走越慢,`EaseInOut` 两端慢、中段快,`EaseCenter` 两端快、中段慢。`CurveMode` 只改变形状,不改变时长与起止值;同一个曲线换模式只是让过程中快慢不同。各模式如何由一条缓进快出曲线换算得到,见[动画曲线](../internals/animation-curves.md#曲线模式)。
下面的演示用同一条正弦曲线,点四个按钮在四种模式之间切换。曲线连续变化,可以直观看出快慢分布。
<ClientOnly>
<RenderDemo :loader="curveModesLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 内置曲线
下面按基础、缓动与双曲三组列出参数与形状;同一组的多条曲线画在一张图里,便于对照。
### 基础曲线
三条基础曲线不接收 `mode` 参数,形状直接由参数决定。
| 曲线 | 参数 |
| ------------- | --------------------- |
| `linear()` | 无 |
| `step(k)` | `k`:阶梯数,取正整数 |
| `constant(k)` | `k`:常数输出值 |
<ClientOnly>
<RenderDemo :loader="basicCurvesLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 缓动曲线
四条曲线都以「缓进快出」为基准,并接收可选的 `mode`;不传时默认 `CurveMode.EaseIn`。它们从 `0` 上升到 `1`,上升速度不同。
| 曲线 | 参数 |
| ----------------- | ------------------------------------ |
| `sin(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` |
| `tan(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` |
| `sec(mode?)` | `mode` 可选,默认 `CurveMode.EaseIn` |
| `pow(exp, mode?)` | `exp` 必需,指数;`mode` 可选 |
<ClientOnly>
<RenderDemo :loader="easingCurvesLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 双曲曲线
三条双曲曲线同样接收可选的 `mode`,默认 `CurveMode.EaseIn`。`k` 是比例参数。
| 曲线 | 参数 |
| -------------------- | -------------------------------------------- |
| `cosh(k = 2, mode?)` | `k` 默认 `2`;`mode` 默认 `CurveMode.EaseIn` |
| `tanh(k = 2, mode?)` | `k` 默认 `2`;`mode` 默认 `CurveMode.EaseIn` |
| `sech(k = 1, mode?)` | `k` 默认 `1`;`mode` 默认 `CurveMode.EaseIn` |
<ClientOnly>
<RenderDemo :loader="specialCurvesLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
曲线公式、模式换算与单条曲线的行为见[动画曲线](../internals/animation-curves.md)。
## 数值渐变
界面里经常需要让一个数值在两次状态之间平滑变化,例如透明度从 `0.25` 到 `1`、圆点从左边移到右边。自己管理执行器、选择对象、绑定激励源会很啰嗦;`transitioned` 把这些收进一个控制器:你只需要告诉它「现在去哪个值」,它负责在当前值与目标值之间平滑推进。
### 获取控制器
先创建控制器,并给它一个初始值、一次变化默认用多久,以及过程中用哪条曲线:
```tsx
// setup
import { transitioned } from '@motajs/render-vue';
import { CurveMode, sin } from '@motajs/animate';
// 初始值 0.25,默认 600ms,曲线用 sin()
const alpha = transitioned(0.25, 600, sin(CurveMode.EaseOut))!;
```
`transitioned(value, time, curve)` 返回一个数值渐变控制器,类型是 `ITransitionedController<number> | null`:`value` 是初始值,`time` 是默认时长(毫秒),`curve` 是速率曲线。它只在组件 `setup` 中调用;在 `setup` 中返回值一定非空,所以这里用 `!` 收窄类型。返回的控制器带一个响应式引用 `ref`(类型 `Ref<number>`),渲染时读 `alpha.ref.value` 就能拿到当前值。
### 执行渐变动画
控制器拿到后,当前值就是初始值。要让数值走向新目标,调用 `set(value, time?)`;省略 `time` 时使用控制器的默认时长:
```tsx
// setup
const expand = () => {
// 从当前值走向 1,使用创建时的 600ms
alpha.set(1);
};
// 组件内容
<g-rect
loc={[40, 92, 120, 88]}
fillStyle="#2f6fed"
alpha={alpha.ref.value}
onClick={expand}
/>;
```
调用 `set(1)` 后,控制器从调用时的当前值出发,在 600ms 内走向 1;渲染函数读 `alpha.ref.value`,所以矩形的透明度会跟着变化。动画进行中再次 `set`,会从当时的当前值转向新目标;`time` 为 `0` 时直接落到目标值。
### 设置渐变参数
如果某一次变化想用不同节奏,或者之后都换一条曲线、一个时长,可以在下一次 `set` 前调用 `mode(curve)` 或 `setTime(time)`:
```tsx
// setup
import { linear } from '@motajs/animate';
// 这一次改用 300ms
alpha.set(0.4, 300);
// 之后的 set 都改用线性曲线与 1200ms
alpha.mode(linear());
alpha.setTime(1200);
```
`mode(curve)` 替换后续 `set` 使用的速率曲线;`setTime(time)` 替换后续 `set` 的默认时长。两者只影响之后的调用,不会重设当前正在进行的渐变。
把三步连起来,就是一次完整的数值渐变。下面的示例同时驱动透明度、位置与进度条:
```tsx
// setup
import { transitioned } from '@motajs/render-vue';
import { CurveMode, linear, sin } from '@motajs/animate';
const alpha = transitioned(0.25, 600, sin(CurveMode.EaseOut))!;
const slide = transitioned(0, 600, sin(CurveMode.EaseOut))!;
const bar = transitioned(0.3, 600, sin(CurveMode.EaseOut))!;
const expand = () => {
alpha.set(1);
slide.set(1, 300);
bar.set(1);
};
bar.mode(linear());
bar.setTime(1200);
// 组件内容
<g-rect loc={[40, 92, 120, 88]} fillStyle="#2f6fed" alpha={alpha.ref.value} />
<g-circle
circle={[204 + slide.ref.value * 192, 140, 12]}
fillStyle="#f2b84b"
/>
<g-rect
loc={[40, 234, 280 * bar.ref.value, 12]}
fillStyle="#7ee787"
/>
```
下面的 live 用三组元素展示 `alpha`、位置与进度条的渐变。
<ClientOnly>
<RenderDemo :loader="alphaLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 颜色渐变
颜色字符串不能直接做数值加减;自己拆成红、绿、蓝、透明四个通道再分别推进,也很麻烦。`transitionedColor` 把颜色当作一个整体:它内部拆通道、同步推进,最后再拼回颜色字符串。
### 获取颜色控制器
```tsx
// setup
import { transitionedColor } from '@motajs/render-vue';
import { CurveMode, sin } from '@motajs/animate';
const fill = transitionedColor('#2f6fed', 600, sin(CurveMode.EaseOut))!;
```
`transitionedColor(color, time, curve)` 返回一个颜色渐变控制器,类型是 `ITransitionedController<string> | null`。`color` 是初始颜色,`time` 是默认时长,`curve` 是速率曲线。它返回的控制器与数值渐变同形,但 `ref.value` 是当前颜色字符串,可以直接交给 `fillStyle`、`strokeStyle`。
支持的颜色写法有十六进制 `#rgb`、`#rgba`、`#rrggbb`、`#rrggbbaa`,以及 `rgb(r, g, b)` 与 `rgba(r, g, b, a)`。只支持这些写法;其他格式不会按预期渐变。
### 执行颜色渐变
```tsx
// setup
const warm = () => {
fill.set('#f2b84b');
};
// 组件内容
<g-rect loc={[40, 80, 180, 140]} fillStyle={fill.ref.value} onClick={warm} />;
```
调用 `set` 后,控制器从当前颜色走向目标颜色;渲染函数读 `fill.ref.value` 得到中间颜色。`set`、`mode`、`setTime` 的用法与数值渐变一致。
### 设置颜色渐变参数
```tsx
// setup
import { linear } from '@motajs/animate';
// 这一次改用 300ms
fill.set('#7ee787', 300);
// 之后的 set 都改用线性曲线与 1200ms
fill.mode(linear());
fill.setTime(1200);
```
`set` 的第二个参数只覆盖这一次的时长;`mode` 与 `setTime` 改的是之后的调用。
把填充色与描边色放进同一个示例:
```tsx
// setup
import { transitionedColor } from '@motajs/render-vue';
import { CurveMode, sin } from '@motajs/animate';
const fill = transitionedColor('#2f6fed', 600, sin(CurveMode.EaseOut))!;
const stroke = transitionedColor(
'rgba(242, 184, 75, 0.9)',
600,
sin(CurveMode.EaseOut)
)!;
fill.set('#f2b84b');
stroke.set('#7ee787');
// 组件内容
<g-rect loc={[40, 80, 180, 140]} fillStyle={fill.ref.value} />
<g-circle
circle={[320, 150, 56]}
stroke
strokeStyle={stroke.ref.value}
lineWidth={10}
/>
```
下面的 live 同时渐变填充色与描边色。
<ClientOnly>
<RenderDemo :loader="colorLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 循环渐变
呼吸灯、闪烁这类效果需要数值在两个端点之间反复往返。每次到端点都手动重设目标,很容易接不上;`cycledTransition` 把往返过程包成一个自动循环的控制器。
### 获取循环控制器
```tsx
// setup
import { cycledTransition } from '@motajs/render-vue';
import { CurveMode, sin } from '@motajs/animate';
// 在 0.25 与 1 之间往返,单程 900ms
const glow = cycledTransition(0.25, 1, 900, sin(CurveMode.EaseOut))!;
```
`cycledTransition(min, max, time, curve, maxStart = false)` 返回一个循环渐变控制器,类型是 `ICycledTransitionController | null`。`min` 与 `max` 是循环的两个端点,`time` 是单程耗时(毫秒),`curve` 是单程使用的速率曲线;`maxStart` 为 `true` 时从 `max` 开始,否则从 `min` 开始。控制器返回后会自动开始循环,组件卸载时停止,不需要手动清理。
### 读取循环值
循环已经自动开始,渲染时读 `glow.ref.value` 就能拿到当前值:
```tsx
// 组件内容
<g-circle circle={[180, 150, 80]} fillStyle="#2f6fed" alpha={glow.ref.value} />
```
这个圆形的透明度会在 0.25 与 1 之间反复变化。到端点后控制器会自动把目标切到另一端,不需要再调用 `set`。
### 设置循环参数
```tsx
// setup
import { linear } from '@motajs/animate';
const narrow = () => {
glow.setRange(0.5, 1);
};
glow.mode(linear());
glow.setTime(1200);
// 组件内容
<g-circle
circle={[180, 150, 80]}
fillStyle="#2f6fed"
alpha={glow.ref.value}
onClick={narrow}
/>;
```
`setRange(min, max)` 修改循环的两个端点,并立即按新区间重新确定这一次的目标;`mode(curve)` 与 `setTime(time)` 修改后续单程使用的曲线与时长。
把两个循环放进同一个示例:
```tsx
// setup
import { cycledTransition } from '@motajs/render-vue';
import { CurveMode, linear, sin } from '@motajs/animate';
const glow = cycledTransition(0.25, 1, 900, sin(CurveMode.EaseOut))!;
const core = cycledTransition(0.5, 1, 900, linear(), true)!;
const widen = () => {
glow.setRange(0.5, 1);
};
// 组件内容
<g-circle circle={[180, 150, 80]} fillStyle="#2f6fed" alpha={glow.ref.value} />
<g-circle circle={[180, 150, 38]} fillStyle="#f2b84b" alpha={core.ref.value} />
```
下面的 live 用两个滑动条分别调整循环的起点与终点,轨道上的圆点显示当前值。
<ClientOnly>
<RenderDemo :loader="cycleLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
需要编排多对象、控制激励源或直接操作单个数值渐变时,继续读[动画曲线](../internals/animation-curves.md)、[动画激励](../internals/animation-excitation.md)、[动画执行器](../internals/animation-runner.md)与[渐变执行器](../internals/animation-transition.md)。
<script setup>
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
const curveModesLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-modes.tsx');
const basicCurvesLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curves-basic.tsx');
const easingCurvesLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curves-easing.tsx');
const specialCurvesLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curves-special.tsx');
const alphaLoader = () =>
import('../../.vitepress/components/demos/ui/animation-alpha.tsx');
const colorLoader = () =>
import('../../.vitepress/components/demos/ui/animation-color.tsx');
const cycleLoader = () =>
import('../../.vitepress/components/demos/ui/animation-cycle.tsx');
</script>
+40 -26
View File
@@ -2,14 +2,15 @@
本指南只讲画屏幕 / 写 UI:怎样用 TSX 画出界面、摆好位置、处理交互、拆成组件,以及 UI 系统与性能的取舍。数据端、存档与录像、插件系统、编辑器等与绘制屏幕关系不紧密的系统不在这里讲,仍见中级 / 高级教程;普通教程只保留主要的渲染逻辑,具体写法集中到本指南。
本指南只收现有 27 篇自定义 UI 文档,不新增系统文档,也不增设系统页面。
本指南只收现有 32 篇自定义 UI 文档,内容分为渲染基础、渲染进阶与渲染底层三层;不新增系统文档,也不增设系统页面。
## 两级结构
## 三级结构
| 分区 | 定位 | 页面数 |
| -------- | -------------------------------------------- | ------ |
| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 |
| 渲染进阶 | 响应式、事件、组件化、UI 系统/性能与完整示例 | 17 |
| 分区 | 定位 | 页面数 |
| -------- | ---------------------------------------------- | ------ |
| 渲染基础 | 模板、元素、坐标、图形、文字与元素属性 | 10 |
| 渲染进阶 | 响应式、事件、动画、组件化、UI 系统/性能与示例 | 18 |
| 渲染底层 | 动画曲线、动画激励、执行器与渐变的内部实现 | 4 |
分层是深度标签,不是领域分类:同一层里可能既有元素,也有组件或示例;读到哪一层取决于你要解决的问题,不必按层读完全部页面。
@@ -18,6 +19,8 @@
- **完全没写过 UI**:从 [UI 通用模板(TSX)](./basics/ui-template.md) 起步,先拿模板跑起来,再用 [UI 入门](./basics/ui-basics.md) 认识标签、组件与渲染树。
- **写过基础界面,想加交互与组件**:从[响应式](./advanced/reactivity.md)接手,把状态、事件与条件渲染接进已有界面。
- **想了解 UI 系统与性能**:从 [UI 系统](./advanced/ui-system.md)读起,再看 [UI 性能](./advanced/ui-performance.md)的日常优化习惯。
- **想让界面元素平滑变化**:从[动画](./advanced/animation.md)入手,用 `transitioned`、`transitionedColor` 与 `cycledTransition` 做数值、颜色和循环渐变。
- **想弄清动画曲线与底层怎么推进**:先读[动画曲线](./internals/animation-curves.md),再看[动画激励](./internals/animation-excitation.md)、[动画执行器](./internals/animation-runner.md)与[渐变执行器](./internals/animation-transition.md)。
## 阅读路径
@@ -25,8 +28,9 @@
- **从静态到交互**:[响应式](./advanced/reactivity.md) → [事件与交互](./advanced/events.md) → [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) → [按键与快捷键](./advanced/hotkey-in-ui.md) → [什么是组件](./advanced/what-is-component.md) → [自定义组件](./advanced/custom-components.md)。适合界面已经画出来、要接数据和操作的时候。
- **做一个完整面板**:[示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) → [示例(二)道具网格](./advanced/inventory-example-2-grid.md) → [示例(三)详情区](./advanced/inventory-example-3-detail.md) → [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) → [示例(五)交互与状态](./advanced/inventory-example-5-state.md) → [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md)。适合把零件装成背包 / 装备面板。
- **改内置 UI 或做性能取舍**:[什么是组件](./advanced/what-is-component.md) → [内置组件:基础](./advanced/builtin-basic.md) → [内置组件:布局](./advanced/builtin-layout.md) → [内置组件:文本](./advanced/builtin-text.md) → [自定义组件](./advanced/custom-components.md) → [UI 系统](./advanced/ui-system.md) → [UI 性能](./advanced/ui-performance.md)。适合替换现成控件或处理缓存与列表开销。
- **让数值与颜色动起来**:[响应式](./advanced/reactivity.md) → [动画](./advanced/animation.md) → 需要更深时读[动画曲线](./internals/animation-curves.md) → [动画激励](./internals/animation-excitation.md) → [动画执行器](./internals/animation-runner.md) / [渐变执行器](./internals/animation-transition.md)。适合给界面加过渡、循环闪烁或颜色变化。
四条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。
五条路径都建议先读 [UI 通用模板(TSX)](./basics/ui-template.md);模板是后面所有页面的起点。
## 页面目录
@@ -47,25 +51,35 @@
### 渲染进阶
| 篇目 | 一句话说明 | 前置 |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) |
| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) |
| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) |
| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) |
| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) |
| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) |
| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) |
| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) |
| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) |
| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) |
| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) |
| 篇目 | 一句话说明 | 前置 |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [响应式](./advanced/reactivity.md) | 数据变化如何自动推到画布元素,以及渲染函数读到什么才算依赖 | [UI 入门](./basics/ui-basics.md)、[第一个静态界面](./basics/first-static-ui.md) |
| [事件与交互](./advanced/events.md) | 点击、按下、抬起、移动、悬停与滚轮的捕获与冒泡 | [容器与坐标](./basics/container-and-coordinates.md)、[响应式](./advanced/reactivity.md) |
| [条件渲染与循环渲染](./advanced/conditional-and-list-rendering.md) | 用 `hidden` 或三元做条件、用 `.map()` 做循环 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [按键与快捷键](./advanced/hotkey-in-ui.md) | 按键指令、分组、作用域,以及组件里怎么接 | [响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [什么是组件](./advanced/what-is-component.md) | 组件最基本的形态、props 的传法,以及组件与 `GameUI` 的关系 | [UI 入门](./basics/ui-basics.md) |
| [内置组件:基础](./advanced/builtin-basic.md) | `Input`、`Icons`、`Arrow`、`Selection`、`Progress`、`Background` 与 `Slider` | [什么是组件](./advanced/what-is-component.md) |
| [内置组件:布局](./advanced/builtin-layout.md) | `Scroll`、`Page`、`List` 与 `ListPage` 的区域与列表用法 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [内置组件:文本](./advanced/builtin-text.md) | `TextContent` 的折行与打字机、`ScrollText` 的自动滚动 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [自定义组件](./advanced/custom-components.md) | 怎么接收参数、发事件、留出内容位置与透传属性 | [什么是组件](./advanced/what-is-component.md)、[内置组件:基础](./advanced/builtin-basic.md) |
| [动画](./advanced/animation.md) | 用曲线驱动 `transitioned`、`transitionedColor` 与 `cycledTransition`,让数值、颜色平滑变化或循环 | [响应式](./advanced/reactivity.md)、[UI 入门](./basics/ui-basics.md) |
| [UI 系统](./advanced/ui-system.md) | 控制器、实例与栈:打开关闭、隐藏显示与显示策略 | [事件与交互](./advanced/events.md) |
| [UI 性能](./advanced/ui-performance.md) | 一组日常习惯,用来减少不必要的绘制与内存占用 | [层级、变换与性能](./basics/layer-transform-performance.md)、[UI 系统](./advanced/ui-system.md) |
| [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md) | 定下背包 / 装备面板的目标、组件拆分与骨架 | [第一个静态界面](./basics/first-static-ui.md)、[容器与坐标](./basics/container-and-coordinates.md) |
| [示例(二)道具网格](./advanced/inventory-example-2-grid.md) | 把道具数据、`ItemCell` 与 `ItemGrid` 填进左侧,让网格能显示与选中 | [示例(一)目标与骨架](./advanced/inventory-example-1-skeleton.md)、[基础图形](./basics/basic-shapes.md) |
| [示例(三)详情区](./advanced/inventory-example-3-detail.md) | 用 `ItemDetail` 填右侧:名称、数量、描述与空选中提示 | [示例(二)道具网格](./advanced/inventory-example-2-grid.md)、[文字](./basics/text.md)、[通用参数](./basics/common-props.md) |
| [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md) | 把普通网格换成 `Scroll`,并说明渲染树、事件与数据流的变化 | [示例(三)详情区](./advanced/inventory-example-3-detail.md)、[内置组件:布局](./advanced/builtin-layout.md) |
| [示例(五)交互与状态](./advanced/inventory-example-5-state.md) | 加 `ActionBar`:装备、使用、关闭,并把状态收口到面板 | [示例(四)滚动与列表](./advanced/inventory-example-4-scroll.md)、[响应式](./advanced/reactivity.md)、[事件与交互](./advanced/events.md) |
| [示例(六)动画、拆分与注册](./advanced/inventory-example-6-animation-and-register.md) | 让选中态与提示动起来,把代码落回文件并注册成 `GameUI` | [示例(五)交互与状态](./advanced/inventory-example-5-state.md)、[自定义组件](./advanced/custom-components.md)、[UI 系统](./advanced/ui-system.md) |
### 渲染底层
| 篇目 | 一句话说明 | 前置 |
| ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [动画曲线](./internals/animation-curves.md) | `ExcitationCurve`、`CurveMode`、内置曲线与曲线计算函数 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [动画激励](./internals/animation-excitation.md) | 激励源怎样驱动受激励对象,以及变速器与分频器如何接入 | [动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [动画执行器](./internals/animation-runner.md) | `Animater` 把多个对象的多个步骤组织成计划组并按时执行 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
| [渐变执行器](./internals/animation-transition.md) | `Transition` 让单个数值平滑靠近目标值,处理曲线与结尾参考 | [动画激励](./internals/animation-excitation.md)、[动画](./advanced/animation.md)、[响应式](./advanced/reactivity.md) |
## 边界与注意
@@ -0,0 +1,535 @@
# 动画曲线
曲线把时间进度映射成数据取值:时间完成度从 `0` 走到 `1`,曲线返回一个数,动画系统再用它让数值从起始值逐步走到目标值。本篇是曲线的完整参考:先讲类型与四种模式,再按基础、缓动、双曲三组逐条列出内置曲线,每条曲线都配一个实时曲线图,带参数的曲线还可以在图上调整参数,最后汇总把曲线组合、变换、拼接与多维合并的计算函数。内置形状曲线与分组对照图的纵轴固定为 `0` 到 `1`;运算与变换的实时图按来源与结果的实际输出自适应纵轴范围,不裁剪曲线。高层用法与形状示例见[动画](../advanced/animation.md);单个数值的连续渐变见[渐变执行器](./animation-transition.md)。
## 前置知识
阅读本篇前,建议先读完:
- [动画](../advanced/animation.md)
- [响应式](../advanced/reactivity.md)
## 曲线与数据映射
曲线的类型是 `ExcitationCurve`,它只接收一个时间完成度,返回一个数:
```ts
export type ExcitationCurve = (progress: number) => number;
```
- 输入是时间完成度,范围是 `0` 到 `1`;下面公式里记作 `x`。类型声明里的参数名是 `progress`,两者指同一个值。
- 输出没有范围限制。动画系统不会把它裁剪到 `0` 到 `1`。
- 曲线本身不知道起始值与目标值;它只回答「进度到这里时,映射结果是多少」。把结果用于计算当前值的动作由动画接口或执行器完成。
```ts
import { linear } from '@motajs/animate';
// 匀速曲线:x 为 0.5 时返回 0.5
const curve = linear();
console.log(curve(0.5));
```
## 曲线模式
同一条曲线,换一个模式就会得到不同的快慢分布;先认识这四个模式,后面带 `mode` 参数的曲线才有共同的参照。
`CurveMode` 是曲线的模式枚举,默认值是 `CurveMode.EaseIn`:
```ts
export const enum CurveMode {
/** 缓进快出 */
EaseIn,
/** 快进缓出 */
EaseOut,
/** 缓进缓出,中间快 */
EaseInOut,
/** 快进快出,中间缓 */
EaseCenter
}
```
| 模式 | 含义 | 形状 |
| ---------------------- | ---------------- | ------------------------------ |
| `CurveMode.EaseIn` | 缓进快出 | 从起点慢慢加速,越接近终点越快 |
| `CurveMode.EaseOut` | 快进缓出 | 起步快,接近终点逐渐减速 |
| `CurveMode.EaseInOut` | 缓进缓出,中间快 | 两端慢、中段最快 |
| `CurveMode.EaseCenter` | 快进快出,中间缓 | 两端快、中段最慢 |
### 模式换算
已经有一条按「缓进快出」写好的曲线时,不必为四种模式各写一份;`applyCurveMode` 能在它外面套一层换算,得到新的形状。`applyCurveMode(func, mode)` 接收一条「缓进快出」曲线 $f(x)$,返回套用模式后的新曲线 $g(x)$:
| 模式 | 换算 |
| ------------ | ------------------------------------------------------------------------------------ |
| `EaseIn` | $g(x) = f(x)$ |
| `EaseOut` | $g(x) = 1 - f(1 - x)$ |
| `EaseInOut` | $x < 0.5$ 时 $g(x) = \frac{f(2x)}{2}$;否则 $g(x) = 1 - \frac{f(2 - 2x)}{2}$ |
| `EaseCenter` | $x < 0.5$ 时 $g(x) = \frac{1 - f(1 - 2x)}{2}$;否则 $g(x) = \frac{1 + f(2x - 1)}{2}$ |
```ts
import { applyCurveMode, CurveMode } from '@motajs/animate';
// 把一条缓进快出曲线 f(x) = x^2 换成快进缓出
const easeOut = applyCurveMode((x: number) => x * x, CurveMode.EaseOut);
```
## 基础曲线
基础曲线不接收 `mode` 参数,形状只由自身参数决定。下面每个 live 都使用 `0` 到 `1` 的纵轴。
### 线性曲线 linear()
没有参数,把输入 `x` 原样输出:
$$
f(x) = x,\quad x\in[0,1]
$$
输出始终在 `0` 到 `1`。下面的 live 没有控件,曲线固定为一条直线。
<ClientOnly>
<RenderDemo :loader="linearCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 阶梯曲线 step(k)
参数 `k` 是分段数,取正整数。进度每走 `1/k`,输出跳变一次:
$$
f(x) = \frac{\lfloor x k \rfloor}{k},\quad x\in[0,1]
$$
live 把 `k` 限制在 `2` 到 `12`;`k` 越大,阶梯越细,输出仍在 `0` 到 `1`。
<ClientOnly>
<RenderDemo :loader="stepCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 常数曲线 constant(k)
参数 `k` 是常数值,输出不随进度变化:
$$
f(x) = k,\quad x\in[0,1]
$$
输出始终等于 `k`,可以落在 `0` 到 `1` 之外。live 为了让曲线留在纵轴内,把 `k` 限制在 `0` 到 `1`;调整时看到的仍是同一条水平线。
<ClientOnly>
<RenderDemo :loader="constantCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 缓动曲线
缓动曲线以「缓进快出」为基准,接收可选的 `mode`,不传时默认 `CurveMode.EaseIn`。下面给出的是基准形状公式;切换模式后,曲线按上一节的换算改变快慢分布。
### 正弦曲线 sin(mode?)
参数 `mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = 1 - \cos\left(\frac{x\pi}{2}\right),\quad x\in[0,1]
$$
基准形状从 `0` 走到 `1`。live 用四个按钮切换 `CurveMode`,曲线连续变化,可以直接看出快慢分布。
<ClientOnly>
<RenderDemo :loader="sinCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 正切曲线 tan(mode?)
参数 `mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = \tan\left(\frac{x\pi}{4}\right),\quad x\in[0,1]
$$
<ClientOnly>
<RenderDemo :loader="tanCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 正割曲线 sec(mode?)
参数 `mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = \sec\left(\frac{x\pi}{3}\right) - 1,\quad x\in[0,1]
$$
<ClientOnly>
<RenderDemo :loader="secCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 幂曲线 pow(exp, mode?)
`exp` 是指数,必需;`mode` 可选,默认 `CurveMode.EaseIn`。下面公式里把 `exp` 记作 `n`:
$$
f(x) = x^{n},\quad x\in[0,1]
$$
live 把 `exp` 限制在 `0.5` 到 `4`;`exp > 0` 时输出仍在 `0` 到 `1`。
<ClientOnly>
<RenderDemo :loader="powCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 双曲曲线
三条双曲曲线同样接收可选的 `mode`,默认 `CurveMode.EaseIn`。`k` 是比例参数。
### 双曲余弦曲线 cosh(k = 2, mode?)
`k` 默认 `2`;`mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = \frac{\cosh(xk) - 1}{\cosh(k) - 1},\quad x\in[0,1]
$$
<ClientOnly>
<RenderDemo :loader="coshCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 双曲正切曲线 tanh(k = 2, mode?)
`k` 默认 `2`;`mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = 1 + \frac{\tanh((x - 1)k)}{\tanh(k)},\quad x\in[0,1]
$$
<ClientOnly>
<RenderDemo :loader="tanhCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 双曲正割曲线 sech(k = 1, mode?)
`k` 默认 `1`;`mode` 可选,默认 `CurveMode.EaseIn`:
$$
f(x) = \frac{1 - \operatorname{sech}(xk)}{1 - \operatorname{sech}(k)},\quad x\in[0,1]
$$
<ClientOnly>
<RenderDemo :loader="sechCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 曲线运算
现成曲线不够用时,不必从零写函数:先拿两条曲线做逐点运算,就能拼出叠加、衰减或复合后的形状。这一组函数把两条曲线逐点做运算,返回一条新曲线。下面的实时图里,蓝色与黄色是两条来源曲线,绿色是结果;纵轴按来源与结果的实际输出自适应,超出 `0` 到 `1` 的结果也会完整画出,函数本身不裁剪。
| 函数 | 结果 |
| -------------------------- | -------------------------- |
| `addCurve(curve1, curve2)` | $h(x) = f(x) + g(x)$ |
| `subCurve(curve1, curve2)` | $h(x) = f(x) - g(x)$ |
| `mulCurve(curve1, curve2)` | $h(x) = f(x) \cdot g(x)$ |
| `divCurve(curve1, curve2)` | $h(x) = \frac{f(x)}{g(x)}$ |
| `powCurve(curve1, curve2)` | $h(x) = f(x)^{g(x)}$ |
| `compositeCurve(c1, c2)` | $h(x) = c_1(c_2(x))$ |
`compositeCurve` 是函数复合,`curve1` 是外层、`curve2` 是内层。其余五个函数都按同一进度逐点取值。
```ts
import { addCurve, constant, mulCurve, sin } from '@motajs/animate';
// 在正弦曲线上叠加一个固定偏移,再整体放大
const lifted = addCurve(sin(), constant(0.2));
const doubled = mulCurve(lifted, constant(2));
```
### 相加 addCurve
两条来源曲线逐点相加。结果可能超过 `1`,图中会按实际范围完整显示。
<ClientOnly>
<RenderDemo :loader="addCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 相减 subCurve
第一条曲线减第二条曲线。结果可能低于 `0`,图中同样按实际范围完整显示。
<ClientOnly>
<RenderDemo :loader="subCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 相乘 mulCurve
两条来源曲线逐点相乘。两条来源都落在 `0` 到 `1` 时,结果也落在 `0` 到 `1`。
<ClientOnly>
<RenderDemo :loader="mulCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 相除 divCurve
第一条曲线除以第二条曲线。分母必须避开 `0`,示例用常数 `0.5` 作分母;结果超过 `1` 时按实际范围完整显示。
<ClientOnly>
<RenderDemo :loader="divCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 取幂 powCurve
第一条曲线作底数,第二条曲线作指数。底数保持非负时结果才有实数意义;示例用 `linear()` 作底、常数 `2` 作指数。
<ClientOnly>
<RenderDemo :loader="powCalcLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 复合 compositeCurve
`compositeCurve(curve1, curve2)` 让外层 `curve1` 接收内层 `curve2` 的输出。示例的外层是 `sin()`,内层是 `pow(2)`。
<ClientOnly>
<RenderDemo :loader="compositeCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 曲线变换
想保留曲线的基本形状,只把它整体抬高、翻转或压扁时,用这些变换,比重新写一条曲线省事。这一组函数改变一条曲线的整体位置、方向或尺度。下面的实时图按来源与结果的实际输出自适应纵轴范围,不裁剪曲线:
| 函数 | 结果 |
| ----------------------------------- | --------------------------- |
| `moveCurve(curve, move = 0)` | $g(x) = f(x) + move$ |
| `oppositeCurve(curve, move = 0)` | $g(x) = move - f(x)$ |
| `scaleCurve(curve, scale = 1)` | $g(x) = f(x) \cdot scale$ |
| `reciprocalCurve(curve, scale = 1)` | $g(x) = \frac{scale}{f(x)}$ |
此外,`normalize(curve)` 把曲线两端的值对齐到 `0` 与 `1`:
$$
g(x) =
\begin{cases}
\dfrac{f(x) - f(1)}{f(0) - f(1)}, & f(0) > f(1),\\[6pt]
\dfrac{f(x) - f(0)}{f(1) - f(0)}, & f(0) < f(1),\\[6pt]
f(x), & f(0) = f(1).
\end{cases}
$$
它只读 `curve(0)` 与 `curve(1)` 来选择参考端点,假定曲线单调,但不会检查或拒绝非单调曲线。非单调曲线仍按这两个端点归一化,中间取值可能落在 `[0, 1]` 之外;两端相等时原样返回。
### 平移 moveCurve
给来源曲线加一个纵向偏移。结果超过 `1` 时按实际范围完整显示。
<ClientOnly>
<RenderDemo :loader="moveCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 取反 oppositeCurve
以 `move` 为基准翻转来源曲线。`move` 为 `1` 时得到上下翻转、重新落回 `0` 到 `1` 的曲线。
<ClientOnly>
<RenderDemo :loader="oppositeCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 缩放 scaleCurve
纵向缩放来源曲线。`scale` 小于 `1` 时整体压低,结果仍在 `0` 到 `1`。
<ClientOnly>
<RenderDemo :loader="scaleCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 倒数 reciprocalCurve
先取来源曲线的倒数,再乘缩放。来源取值在 `0.5` 到 `1`,避开分母过零;结果落在 `0.5` 到 `1`。
<ClientOnly>
<RenderDemo :loader="reciprocalCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 归一化 normalize
来源取 `0.2` 到 `0.8`,归一化后两端对齐到 `0` 与 `1`。它只用两端值决定方向,假定曲线单调,不会拒绝非单调曲线。
<ClientOnly>
<RenderDemo :loader="normalizeLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 曲线拼接
一段动画如果前半段和后半段要用不同节奏,单条曲线表达不了;`sequenceCurve` 能把几条现成曲线按时间比例接起来。`sequenceCurve(seq, duration, scale, move)` 把多条曲线按顺序拼成一条:
- `seq`:曲线数组,按顺序执行。
- `duration`:每段占用的时间比例,范围在 `0` 到 `1` 之间;各段之和通常应设为 `1`。
- `scale`:每段输出在拼接时的缩放比例。
- `move`:每段输出在拼接时的纵向偏移。
```ts
import { linear, sequenceCurve, sin } from '@motajs/animate';
// 参数依次是曲线序列、每段时长占比、每段缩放与每段偏移
const curve = sequenceCurve([linear(), sin()], [0.5, 0.5], [1, 1], [0, 0]);
```
来源段各自都是完整的 `0` 到 `1` 形状,结果按 `duration` 分配的时间段依次取用。下面的实时图把两条来源段都画成完整曲线,绿色结果是两段各占一半时长的拼接结果。
<ClientOnly>
<RenderDemo :loader="sequenceCurveLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
序列过长(超过约 100 段)可能影响性能;需要很多段时,先确认是否可以用公式直接表达。`duration` 之和不为 `1` 时的具体行为不在本篇的保证范围内,需要拼接时按总和 `1` 分配。
## 多维曲线
当一条曲线要同时给出多个分量(例如路径上的横纵坐标),或想把几组一维曲线当成一个整体传递时,就需要多维曲线。多维曲线本质是参数方程:同一个时间完成度同时输出多个值。相关类型有 `ExcitationCurve2D`、`ExcitationCurve3D` 与 `GeneralExcitationCurve`。
拆分把一条多维曲线变成多条一维曲线:
| 函数 | 结果 |
| --------------------- | -------------------------- |
| `splitCurve2D(curve)` | $[c_1(x), c_2(x)]$ |
| `splitCurve3D(curve)` | $[c_1(x), c_2(x), c_3(x)]$ |
| `splitCurve(curve)` | 按维数拆成一维曲线数组 |
合并把多条一维曲线组成一条多维曲线:
| 函数 | 结果 |
| -------------------------------------- | ------------------------------------ |
| `stackCurve2D(curve1, curve2)` | $x \mapsto [c_1(x), c_2(x)]$ |
| `stackCurve3D(curve1, curve2, curve3)` | $x \mapsto [c_1(x), c_2(x), c_3(x)]$ |
| `stackCurve(curves)` | 任意维数的曲线;维数取数组长度 |
```ts
import {
linear,
sin,
splitCurve,
splitCurve2D,
stackCurve2D
} from '@motajs/animate';
// 把一条二维曲线拆成两条一维曲线,再重新合成另一条二维曲线
const [x, y] = splitCurve2D(stackCurve2D(linear(), sin()));
const [backX, backY] = splitCurve(stackCurve2D(x, y));
console.log(backX(0.5), backY(0.5));
```
多维曲线是参数曲线:同一个时间完成度同时给出多个分量,不是一个输入对应一个输出,所以不能画成单张「时间为横轴、单个取值为纵轴」的曲线图。`splitCurve3D` 与 `stackCurve3D` 只是多一维、多一列,`splitCurve` 与 `stackCurve` 则按任意维数处理。
## 边界与注意
- 输出不受 `0` 到 `1` 限制;不要为了「看起来正常」而把结果夹到区间内,否则过冲与回弹会失效。
- `normalize` 只用两端值决定方向,假定曲线单调,但不会检查或拒绝非单调曲线;非单调曲线归一化后,中间取值可能超出 `[0, 1]`。
- `divCurve` 与 `reciprocalCurve` 在分母为 `0` 的位置会产生 `Infinity` 或 `NaN`,组合时要确认除数不会过零。
- `sequenceCurve` 的各段 `duration` 之和通常应设为 `1`;不要依赖总和不为 `1` 时的具体行为。
- 曲线函数应当是纯函数;不要在曲线里读写外部状态,它会在每一帧被反复调用。
<script setup>
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
const linearCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-linear.tsx');
const stepCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-step.tsx');
const constantCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-constant.tsx');
const sinCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-sin.tsx');
const tanCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-tan.tsx');
const secCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-sec.tsx');
const powCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-pow.tsx');
const coshCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-cosh.tsx');
const tanhCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-tanh.tsx');
const sechCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-sech.tsx');
const addCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-add.tsx');
const subCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-sub.tsx');
const mulCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-mul.tsx');
const divCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-div.tsx');
const powCalcLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-pow.tsx');
const compositeCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-composite.tsx');
const moveCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-move.tsx');
const oppositeCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-opposite.tsx');
const scaleCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-scale.tsx');
const reciprocalCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-reciprocal.tsx');
const normalizeLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-normalize.tsx');
const sequenceCurveLoader = () =>
import('../../.vitepress/components/demos/ui/animation-curve-calc-sequence.tsx');
</script>
@@ -0,0 +1,344 @@
# 动画激励
动画不会自己动:需要有人按节奏推一下。动画激励把这件事拆成两半——激励源决定什么时候推,受激励对象决定被推时做什么。动画执行器与渐变执行器都是受激励对象,所以能挂在同一个激励源上。
本篇按「受激励对象是什么、激励源是什么、四种内置激励源怎么用、组件里怎么接」的顺序讲。变速器与分频器本身也是激励源,会放在内置激励源里一起说明。
## 前置知识
阅读本篇前,建议先读完:
- [动画](../advanced/animation.md)
- [响应式](../advanced/reactivity.md)
## 激励模型
系统里有三个角色:
| 角色 | 是什么 | 负责 |
| ------------------------- | ---------------------- | -------------------------------------- |
| `IExcitable<T>` | 受激励对象 | 接收一次负载,执行自己的处理 |
| `IExcitation<T>` | 激励源 | 决定什么时候推进,并管理所有受激励对象 |
| `IExcitableController<T>` | 单个受激励对象的控制器 | 解除这次登记,或手动推进这一个对象 |
「激励」就是按节奏推进一次:激励源把当前的负载交给每个登记过的对象。负载的类型由具体激励源决定;动画系统里的激励源都传数字时间,所以执行器接收的是 `number`。
激励源不关心对象是动画、渐变还是普通回调;动画执行器与渐变执行器都是 `IExcitable<number>`,所以能挂在同一个激励源上。
```mermaid
flowchart LR
S[激励源] -->|负载| A[受激励对象 A]
S -->|负载| B[受激励对象 B]
S -->|add| C[控制器] -->|revoke| S
```
当一个激励源把另一个激励源当作时间来源时,本篇把前者叫 **输入源**,把登记在它上面、接收它推进的对象叫 **接收方**。例如变速器从输入源读取时间,再把换算后的时间交给接收方。
## 受激励对象
`IExcitable<T>` 不需要继承任何类,也没有别的成员;它只要求一个具体方法 `excited(payload: T): void`。激励源每次推进时调用这个方法,`payload` 就是这次传来的负载。
```ts
import { IExcitable } from '@motajs/animate';
// 受激励对象:每次被推进时记下负载
class TimeRecorder implements IExcitable<number> {
last = 0;
excited(payload: number): void {
this.last = payload;
}
}
```
要让激励源每次推进都通知它,需要把它登记进去。`add` 返回一个控制器;控制器只管理这一个对象,不影响同一个源上的其他接收方:
```ts
import { RafExcitation } from '@motajs/animate';
const source = new RafExcitation();
const recorder = new TimeRecorder();
// 登记后,源每推进一次,recorder 就收到一次时间
const controller = source.add(recorder);
// 只推进 recorder 一个对象,不广播给其他接收方
controller?.excite(source.payload());
// 解除登记;之后源不会再推进这个对象
controller?.revoke();
```
`IExcitableController<T>` 就是 `add` 返回的控制器,包含三个成员:
- `excitable`:被登记的那个对象。
- `revoke()`:把对象从当前激励源移除。
- `excite(payload)`:只推进这一个对象,不广播给其他对象。
### 包装函数 excited
如果手上只有一段函数,不想为它单独写一个类,`excited(func, thisArg?)` 可以把它包成 `IExcitable<T>`:
```ts
import { excited } from '@motajs/animate';
// 把函数包成受激励对象;每次激励时函数收到负载
const recorder = excited<number>(payload => {
console.log(payload);
});
```
它返回的对象只有一个 `excited` 方法:每次激励源推进时调用 `func(payload)`,不会替调用方保存状态。包装后的对象可以直接交给 `add`、`onExcited` 等接收 `IExcitable<T>` 的地方。
包装只提供 `excited`,不提供 `revoke` 或 `excite`;要解除登记或单独推进,仍然使用 `add` 返回的控制器。需要保存状态、读取上一次负载或提供多个方法时,写一个实现 `IExcitable<T>` 的类更清楚。
`thisArg` 可选,用来固定 `func` 执行时的 `this`;省略时函数按原来的方式调用。
## 激励源接口
自带激励源之外,有时需要替换节奏或自己实现一个。无论哪种,都要满足同一套契约;内置激励源已经实现好,只有自己写源时才需要逐项实现。
| 成员 | 作用 |
| ----------------- | ----------------------------------------------------- |
| `payload()` | 读取当前负载 |
| `excite(payload)` | 把负载广播给当前所有受激励对象 |
| `add(object)` | 登记一个受激励对象,返回控制器;无法登记时返回 `null` |
| `remove(object)` | 移除一个受激励对象,返回是否移除成功 |
| `destroy()` | 终止激励源,停止继续推进 |
`payload()` 回答「现在的时间或值是多少」,`excite()` 回答「把这一刻发给谁」。帧激励源每帧更新当前时间后调用一次 `excite()`;固定间隔激励源按定时器调用;变速器与分频器则在收到输入源的推进后,按自己的规则再推进接收方。
## 内置激励源
内置激励源分两类:帧激励源与固定间隔激励源负责产生时间,变速器与分频器负责加工另一个激励源的时间或次数。下面每个都先说为什么需要,再给一段最小用法,最后说明接收方会收到什么。
### 帧激励源
界面动画通常希望跟着屏幕刷新走;帧激励源就是这条默认节奏,根渲染器默认也用它。
`RafExcitation` 用 `requestAnimationFrame` 驱动,每一帧把当前时间戳作为负载广播出去。它最直接的用法是接到动画执行器上:
```ts
import { Animater, RafExcitation } from '@motajs/animate';
const source = new RafExcitation();
const animater = new Animater();
// 把执行器登记到帧激励源;之后执行器每帧被推进一次
source.add(animater);
```
接收方拿到的负载是 `requestAnimationFrame` 的时间戳,单位毫秒,例如 `1234.5`。它不是从 `0` 开始的动画时间,而是浏览器给这一帧的时间;相邻两帧的差值反映这一帧间隔了多久。
- `payload()` 返回最近一帧的时间戳。
- 构造时立即开始请求下一帧,所以第一次推进发生在下一帧,不是构造的瞬间。
- `destroy()` 取消尚未执行的帧请求。
渲染器的根元素默认使用一个 `RafExcitation`,所以组件里拿到的动画执行器通常不需要自己创建激励源。
下面的 live 显示当前载荷、相邻两帧的时间差与已过的帧数。
<ClientOnly>
<RenderDemo :loader="rafPayloadLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 固定间隔激励源
有些逻辑只需要稳定节奏,不必跟屏幕刷新同步;固定间隔激励源按定时器推进,节奏由构造时传入的间隔决定。
`IntervalExcitation` 实现 `IIntervalExcitation`,用固定毫秒间隔触发。登记一个接收方后,它会按间隔反复推进:
```ts
import { IntervalExcitation } from '@motajs/animate';
const source = new IntervalExcitation(100);
// 复用前面的 TimeRecorder
const recorder = new TimeRecorder();
// 约每 100ms 推进一次;接收方依次收到 0、100、200……
source.add(recorder);
```
它用内部计数当负载:触发时先把当前计数发出去,再把计数加一个 `interval`。所以接收方依次拿到 `0`、`interval`、`2 × interval`……;`payload()` 返回计数器的当前值,第一次触发后它已经变成 `interval`。
这个计数不跟随真实时间(墙钟时间),也不保证每一次都恰好落在整百毫秒上。需要和真实时间对齐时,使用帧激励源。
### 变速器
需要整体放慢、加速,或让速度平滑变化时,不必改每个动画的时长;把变速器接在一个激励源后面,就能统一改变时间流速。
`ExcitationVariator` 实现 `IExcitationVariator`,本身就是一种 `IExcitation<number>`。它先订阅一个输入源,再把输入时间按当前速度换算成自己的时间,最后用自己的时间推进接收方。
```ts
import { Animater, ExcitationVariator, RafExcitation } from '@motajs/animate';
const input = new RafExcitation();
const variator = new ExcitationVariator();
const animater = new Animater();
// 以帧激励源为输入源;绑定后速度重置为 1
variator.bindExcitation(input);
// 执行器登记在变速器上,收到的是变速器换算后的时间
variator.add(animater);
// 输入时间每前进 10ms,执行器只前进 5ms
variator.setSpeed(0.5);
```
接收方拿到的是变速器时间轴上的时间,不是输入源的原始时间。绑定时它从输入源当前时间起步;之后每次输入推进,它把「输入前进了多少」乘以当前速度,累加到自己的时间上,再发给接收方。`payload()` 返回这个时间。
速度改变的是时间流速,不是动画配置里的时长。一个动画在变速器时间轴上配置为 `400`,速度设为 `0.5` 后,它仍然需要变速器时间轴前进 `400`;只是这段变速器时间现在要用两倍的真实时间才能走完。改变速度不会重算已经过去的时间,只影响之后的推进。
`setSpeed` 必须放在 `bindExcitation` 之后:未绑定时它不会生效。绑定时速度会重置为 `1`,所以先绑定、再设置速度。
下面的 live 显示输出端连续两次时间的差值。切换速度后,相邻两次推进的时间差会随之改变。
<ClientOnly>
<RenderDemo :loader="variatorLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 变速曲线
直接改速度会让时间流速瞬间跳变;需要慢慢加速或减速时,用 `curveSpeed` 在一段时间内按曲线改变速度。
`curveSpeed(curve, time, mode?)` 让速度在 `time` 毫秒内按曲线变化,返回一个 Promise,在曲线结束时兑现。已经有一条曲线在运行时,新曲线会排在它后面。
```ts
import { linear } from '@motajs/animate';
// 在输入源时间 300ms 内,速度从 1 线性降到 0.5
await variator.curveSpeed(x => 1 - 0.5 * x, 300);
```
曲线的输入是这段时间的完成度,输出就是当前速度。第三个参数 `VariatorCurveMode` 决定曲线进度按哪条时间轴计算:
| 模式 | 曲线进度按谁走 |
| --------------------------------- | ---------------------------------------------- |
| `VariatorCurveMode.SourceRelated` | 按输入源的时间走,速度变慢不会拖慢曲线本身 |
| `VariatorCurveMode.SelfRelated` | 按变速器自己的时间走,速度变慢时曲线也一起变慢 |
默认是 `SourceRelated`。
下面的 live 用一条从 `1.5` 降到 `0.25` 的变速曲线演示这一点。它显示当前速度、输出端最后两次推进的时间,以及两者的时间差。速度越高,输出端时间推进越快,相邻两次推进的时间差也越大。
<ClientOnly>
<RenderDemo :loader="curveSpeedLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 分频器
不是每一次激励都需要处理,例如只需要低频刷新的逻辑;分频器把输入源的多次激励压成一次,减少接收方的更新次数。
`ExcitationDivider<T>` 实现 `IExcitationDivider<T>`,也是 `IExcitation<T>`。它接收输入源的每一次推进,但只把其中一部分继续发给接收方。
```ts
import { ExcitationDivider, IntervalExcitation } from '@motajs/animate';
const input = new IntervalExcitation(100);
const divider = new ExcitationDivider<number>();
// 复用前面的 TimeRecorder
const recorder = new TimeRecorder();
// 绑定后分频比为 1,输入推进一次就转发一次
divider.bindExcitation(input);
divider.add(recorder);
// 之后输入每推进 3 次,接收方收到 1 次
divider.setDivider(3);
```
接收方收到的负载仍是输入源传来的那一份,只是有些推进被丢掉了。`payload()` 返回最近一次转发出去的负载;从未绑定输入源时读取它会报错。
分频器改变的是激励次数,不是时间速度。它不能用来让动画整体变慢——那应该使用变速器。`setDivider` 可以在绑定后调用;未绑定时调用不会生效,也不会报错。
`divider` 是当前分频比例,默认 `1`。设置后,下一次输入推进会立即转发一次,之后每隔 `divider` 次输入推进再转发一次。
下面的 live 用固定间隔激励源驱动分频器:左侧是输入源的原始载荷与次数,右侧是接收方实际收到的载荷与次数。改变分频比后,接收方次数按比例减少,但收到的载荷仍是输入源传来的那一份。
<ClientOnly>
<RenderDemo :loader="dividerLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 组件内的激励接入
渲染端把整块 UI 挂在一棵渲染树上,树的最顶层叫根渲染器;它自带一个激励源。渲染端还提供了两个组件内辅助函数,用来把每帧逻辑挂到根渲染器的激励源上。
### 登记受激励对象 onExcited
已经有一个 `IExcitable<number>`,又希望它跟着根渲染器的激励源每帧推进时,用 `onExcited`。手动 `add` 到根激励源也能做到,但组件卸载时容易漏掉移除,留下泄漏;这个函数把登记与清理放在一起。
`onExcited(excitable: IExcitable<number>): void` 接收一个受激励对象,不接收函数。它只能在组件的 `setup` 或生命周期钩子中调用;在组件外调用不会生效。
```ts
import { onExcited } from '@motajs/render-vue';
// 复用前面的 TimeRecorder
const recorder = new TimeRecorder();
// 只在组件 setup 或生命周期钩子中调用
onExcited(recorder);
```
调用后,根渲染器每帧推进时 `recorder.excited(time)` 会收到当前帧的时间戳。它返回 `void`,没有可操作的控制器;组件卸载时会自动移除登记,根渲染器变化时也会在新根上重新登记。不要在组件外使用它,也不要在卸载后继续依赖这个登记。
### 包装函数 onExcitedFunc
每帧逻辑如果只是一段函数,不想先写一个 `IExcitable` 类,用 `onExcitedFunc`。它把函数包成受激励对象再登记,省掉手工包装。
`onExcitedFunc(func: (time: number) => void): void` 接收一个每帧调用的函数,参数是根渲染器当前帧的时间戳。它同样只能在组件的 `setup` 或生命周期钩子中调用;在组件外调用不会生效。
```ts
import { onExcitedFunc } from '@motajs/render-vue';
let elapsed = 0;
// 只在组件 setup 或生命周期钩子中调用
onExcitedFunc(time => {
// time 是根渲染器当前帧的时间戳
elapsed = time;
});
```
它内部用 `excited(func)` 包装后交给 `onExcited`,所以清理行为与 `onExcited` 相同:组件卸载时自动移除登记,根渲染器变化时重新登记。包装后的对象不保存状态;需要读取上一次负载或提供多个方法时,仍然写一个实现 `IExcitable<number>` 的对象,再用 `onExcited` 登记。
## 与两个执行器的关系
`Animater` 与 `Transition` 都实现 `IExcitable<number>`,因此:
- 它们可以绑定任意数字激励源,包括 `RafExcitation`、`IntervalExcitation`、`ExcitationVariator` 与 `ExcitationDivider`。
- 变速器与分频器也是激励源,可以接在执行器前面,分别改变时间流速与激励次数。
高层封装如 `transitioned`、`transitionedColor` 与 `cycledTransition` 也共享同一套根激励源,因此不需要再单独创建时钟。
## 边界与注意
- 变速器与分频器都要先绑定输入源才能工作;变速器未绑定时 `setSpeed` 不生效,分频器从未绑定输入源时读取 `payload()` 会报错。
- 变速器绑定输入源时会把速度重置为 `1`,并把自己的时间对齐到输入源的当前时间;需要别的速度就在绑定之后设置。
- `onExcited` 与 `onExcitedFunc` 只适用于组件内部;组件外要自己创建 `IExcitable` 并手动登记、移除。
- 变速器改变的是时间流速,分频器改变的是激励次数;用分频器让动画变慢会跳过中间帧,不会拉长动画时间。
<script setup>
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
const rafPayloadLoader = () =>
import('../../.vitepress/components/demos/ui/excitation-raf-payload.tsx');
const variatorLoader = () =>
import('../../.vitepress/components/demos/ui/excitation-variator.tsx');
const dividerLoader = () =>
import('../../.vitepress/components/demos/ui/excitation-divider.tsx');
const curveSpeedLoader = () =>
import('../../.vitepress/components/demos/ui/excitation-curve-speed.tsx');
</script>
@@ -0,0 +1,570 @@
# 动画执行器
动画执行器 `Animater` 实现 `IAnimater`,负责把多个动画对象的多个步骤组织成一条时间线。它关心的是「谁在第几步动、下一步什么时候开始」,而不是单个数值的平滑过渡;一个数从当前值靠近目标值,用[渐变执行器](./animation-transition.md)。
## 前置知识
阅读本篇前,建议先读完:
- [动画曲线](./animation-curves.md)
- [动画激励](./animation-excitation.md)
- [动画](../advanced/animation.md)
- [响应式](../advanced/reactivity.md)
## 获取执行器与激励接入
执行器自己不产生时间:它只接收外部传来的时间戳,再据此推进计划。推动它的对象叫**激励源**:例如 `RafExcitation` 每帧把当前时间戳推给执行器一次。没有接上激励源时,计划可以写好,但一步都不会执行。所以动手编排之前,先要知道执行器从哪里来、怎样接上时间。
### 组件内获取
组件里通常不自己创建执行器:手写 `new` 既要记得绑定激励源,又容易在组件卸载后继续持有。`useAnimater(anim?, excitation?)` 返回 `IAnimater | null`,只能在组件的 `setup` 或生命周期钩子中调用;它默认把执行器接到根渲染器的激励源上,根渲染器变化时重新绑定,组件卸载时解除绑定。
不传执行器时,它内部新建一个,并在卸载时一并销毁;传入已有执行器时,只负责绑定与解绑,执行器仍由调用方持有。需要显式指定激励源时,传第二个参数。使用 `useAnimater` 时,不需要自己调用 `destroy()`。
```ts
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` 时,卸载清理已经由它完成。
```ts
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 的当前值,下方色块是步骤段,竖线是播放头。播放头本身也是一条同组同时长的步骤,不是页面定时器。
<ClientOnly>
<RenderDemo :loader="timelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 动画对象的选择
为了让动画系统知道它该如何执行动画、将当前值写入哪个对象,就必须先使用 `animate` 接口来绑定动画对象。`animate(content: IAnimatable): this` 选中的对象必须满足 `IAnimatable`:一个带可写 `value` 的对象;Vue 的 `ref<number>` 就满足这个形状。执行器只改这个字段,不负责把值画到画布。
`animate` 只改变「之后的操作作用在谁身上」,本身不新增步骤,也不移动任何值。同一个对象在一个计划组里可以多次出现,它的步骤编号会继续累加。没有先选对象就调用 `to` 时,执行器不会添加任何步骤——计划看起来写了,实际不会动,所以选择对象要放在写步骤之前。
```ts
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` 不会把它恢复成线性。
```ts
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` 处的输出决定。
```ts
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` 后面,再选下一个对象,读起来就是「这段结束后,再让谁动」:
```ts
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` 开始;找不到对应步骤时不会建立这个关联,若之前已经挂过触发,基准保持原样,否则后续步骤随组开始。
```ts
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` 毫秒。没有它,两段要么完全同时开始,要么等前一段结束。
```ts
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` 相同,只是基准从「步骤结束」改为「步骤开始」。
```ts
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 |
```ts
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` 是组执行后的等待时长(毫秒),组内步骤、开始触发与结束触发全部结束后再等待这么久,计划组才真正结束。
- 后一个计划组会等前一个计划组全部结束之后才开始,因此组与组之间不会重叠。
```ts
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` 才开始。
```ts
// 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` 结束的同一刻启动。
时间轴视图:色块是步骤段,竖线是播放头。
<ClientOnly>
<RenderDemo :loader="sequentialTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:两个圆点分别表示 `x` 与 `y` 的当前值。
<ClientOnly>
<RenderDemo :loader="sequentialPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 并行执行
这个示例表示:`x` 与 `y` 同时开始,各自走向自己的目标。
```ts
// 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;结束本组,当前对象清空
```
两条步骤都没有挂触发点,所以都会随组开始;它们只共享开始时刻,不共享目标、时长或曲线。
时间轴视图:两条步骤段从同一刻开始。
<ClientOnly>
<RenderDemo :loader="parallelTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:两个值同时变化。
<ClientOnly>
<RenderDemo :loader="parallelPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 延迟与重叠
这个示例表示:`x` 先开始,`y` 在 `x` 开始 300ms 后启动,两者重叠 600ms。
```ts
// 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` 中段开始。
<ClientOnly>
<RenderDemo :loader="delayedTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:`x` 先动,`y` 稍后启动。
<ClientOnly>
<RenderDemo :loader="delayedPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 两个计划组
这个示例表示:组 1 的 `x` 全部结束后,组 2 的 `y` 才开始;组间不需要额外写等待。
```ts
// 组 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
```
时间轴视图:两组首尾相接,中间没有重叠。
<ClientOnly>
<RenderDemo :loader="relayTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:`x` 完成后,`y` 才从 0 开始。
<ClientOnly>
<RenderDemo :loader="relayPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 查询与等待指定步骤
这个示例表示:先读出 `y` 这条步骤的目标与时长,再只等待 `y` 结束。
```ts
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` 那一段。
<ClientOnly>
<RenderDemo :loader="queryTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:先显示查到的 `y` 目标与时长,再播放数值。
<ClientOnly>
<RenderDemo :loader="queryPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
### 中途改道
这个示例表示:`x` 的第一段走到 700ms 时被第二段接管,改为走回 0;`y` 仍按自己的节奏走完。
```ts
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 处截断,第二段从那里接上。
<ClientOnly>
<RenderDemo :loader="retargetTimelineLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
播放视图:`x` 在改道后从当前值走回 0,`y` 继续走完。
<ClientOnly>
<RenderDemo :loader="retargetPlaybackLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 与渐变执行器的分工
`Animater` 负责多个对象、多个步骤的编排;只是让单个数值连续靠近目标值时,用[渐变执行器](./animation-transition.md)。
## 边界与注意
- 同一个对象在同一时刻只能开始一条步骤:两条步骤同时启动会报错并跳过后一条;启动时刻更晚时,前一条会立刻结束再开始新的。
- `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>
@@ -0,0 +1,253 @@
# 渐变执行器
渐变执行器 `Transition` 实现 `ITransition`,负责让一个数值平滑地靠近目标值。它只处理一个数值、一段时长和一条曲线;需要给多个值排先后、控制并行关系时,使用[动画执行器](./animation-runner.md)。
## 模型
一次渐变只有四样东西:
| 组成 | 是什么 |
| ---------- | --------------------------------------------------------- |
| 当前值 | 可写对象上的 `value`,渐变过程中由执行器更新 |
| 目标值 | 这次要靠近的数,由 `to` 的第一个参数给出 |
| 时长与曲线 | 用多久走完,以及过程中快慢怎么变化 |
| 激励源 | 按固定节奏推动执行器的来源,由 `useTransition` 或手动接入 |
`IAnimatable` 是动画对象的形状:一个带可写 `value` 的对象,Vue 的 `ref<number>` 也满足这个形状。当前值由执行器改写,调用方只读它。
曲线决定的是「已经走了多远」。它接收时间进度 `progress`(`0` 到 `1`),返回一个数;这个数表示此时刻动画的完成度:为 `0` 时动画处于起点,为 `1` 时刚好执行到目标值,中间按曲线返回的比例推进。
曲线返回值超出 `0` 到 `1` 时,当前值会越过目标值,或回到起始值之外。
调用 `to` 后,执行器记下目标值、时长与曲线。之后每次激励,它就让当前值向目标值靠近一点;到达结尾时,按结尾参考决定最终写什么值。没有激励源,`to` 不会开始。
```mermaid
flowchart LR
E[激励源] -->|excited| T[Transition]
T -->|更新当前值| V[IAnimatable.value]
C[to:目标值 / 时长 / 曲线] --> T
```
`ITransition` 本身是一个受激励对象(`IExcitable<number>`):它接收激励源按节奏传来的数字时间戳,再推进自己的渐变。通过 `bindExcitation` 接入激励源、通过 `unbindExcitation` 解除。组件里通常交给 `useTransition`;不在组件内,或需要接到自定义激励源时,才手动绑定。
下面的 live 用真实的 `Transition` 驱动数值。当前值与目标值同时显示,按钮会重新设定目标,执行器从当前值继续渐变。
<ClientOnly>
<RenderDemo :loader="transitionLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 执行器
自己 `new` 执行器还要手动找激励源并处理解绑,组件卸载时很容易漏掉清理;`useTransition` 把这些事收在一处。它必须在组件的 `setup` 或生命周期钩子里调用:它会把执行器绑定到根渲染器的激励源,并在组件卸载时解除绑定。
```tsx
// setup
import { defineComponent, ref } from 'vue';
import { useTransition } from '@motajs/render-vue';
const MyPanel = defineComponent(() => {
const opacity = ref(0);
// 只能在组件 setup 或生命周期钩子里调用
const transition = useTransition()!;
// 之后的 transition.transition(...).to(...) 都通过它执行
return () => <container loc={[0, 0, 100, 100]} alpha={opacity.value} />;
});
```
`useTransition(tran?, excitation?)` 返回 `ITransition | null`。两个参数都可选:`tran` 是已有的执行器,`excitation` 是显式指定的激励源。省略时,函数会新建一个 `Transition`,并绑定根渲染器的激励源。
不传 `tran` 时,执行器由 `useTransition` 创建,组件卸载时会解除绑定并销毁它;传入 `tran` 时,函数只负责绑定与解绑,执行器仍由调用方持有。根渲染器变化时,两种情况都会重新绑定到新的激励源。
不在组件内,或需要接到自定义激励源时,才自己创建执行器并手动绑定。`RafExcitation` 是一个每帧给出时间戳的激励源,`Transition` 是渐变执行器本身:
```ts
import { RafExcitation, Transition } from '@motajs/animate';
const excitation = new RafExcitation();
const transition = new Transition();
// 绑定后执行器才会收到每一帧的时间戳
transition.bindExcitation(excitation);
// 不再使用时解绑
transition.unbindExcitation();
```
手动创建时,解绑与销毁由调用方负责;`useTransition` 只是替组件内场景处理了这些收尾。
## 对象选择
`to` 只会改「当前选中的对象」,所以开始渐变的下一步是告诉执行器改谁;不先选对象,后面的目标值没有落点。
`transition(animatable)` 选择后续 `to` 作用的数值对象,返回执行器本身,可以继续链式调用。
```ts
const opacity = ref(0);
const transition = useTransition()!;
transition.transition(opacity).to(1, 300);
```
同一个执行器可以依次选择不同对象,各自调用 `to`;每个对象的渐变独立进行,`wait` 也按对象区分。`transition` 只改变「之后调用 `to` 时作用在谁身上」,不会停止之前已经在进行的渐变。
```ts
import { ref } from 'vue';
import { linear, sin } from '@motajs/animate';
import { useTransition } from '@motajs/render-vue';
const leftBar = ref(0);
const rightBar = ref(1);
const transition = useTransition()!;
function playBars() {
// 选中 leftBar,后面的 to 只作用于它
transition.transition(leftBar).curve(linear()).to(1, 600);
// 再选中 rightBar,两条渐变同时推进
transition.transition(rightBar).curve(sin()).to(0, 600);
}
```
`playBars` 调用后,`leftBar` 与 `rightBar` 各自有一段正在进行的渐变;执行器每次被激励都会把两条都推进一次。它们只共享激励源,不共享目标、时长或曲线。
## 曲线设置
同样一段时间,是匀速走完还是先慢后快,由曲线决定;想要淡入淡出、回弹或强调结尾时,需要在这里换掉默认的线性曲线。
`curve(curve)` 设置后续 `to` 使用的速率曲线,直到下一次设置;不设置时使用线性曲线。曲线决定过程中的快慢,`time` 决定总耗时。
```ts
import { sin } from '@motajs/animate';
transition.transition(opacity).curve(sin()).to(1, 300);
```
一次渐变会使用调用 `to` 时已经设好的曲线;之后再改 `curve`,不会影响已经开始的那一次。需要让不同目标使用不同节奏时,在每次 `to` 前重新设置。各条曲线的形状见[动画曲线](./animation-curves.md)。
## 开始渐变
前面的选择与曲线只是准备,真正让数值开始变化的是 `to`;没有它,执行器不会产生任何一段渐变。
`to(value, time, end?)` 让当前选中的对象从自己的当前值出发,在 `time` 毫秒内走向 `value`。它需要两个前提:已经用 `transition` 选择了对象,并且已经绑定激励源;缺少任意一项时,调用不会开始渐变。使用顺序是:先用 `transition(对象)` 选中要改的数值,再用 `curve(...)` 选好曲线,最后调用 `to(...)` 启动渐变。
同一个对象在渐变途中再次调用 `to`,会从当前值重新出发,把目标改为新的值。之前那次渐变的等待仍会在新目标完成时兑现。
```ts
const opacity = ref(0);
function fadeIn() {
transition.transition(opacity).to(1, 600);
}
function dim() {
// 如果 fadeIn 还没结束,会从当前值出发,把目标改成 0.4
transition.transition(opacity).to(0.4, 300);
}
```
## 结尾参考
曲线走到终点时未必等于目标值,最后该写哪一个需要明确;`EndRelation` 就是在回答这个问题,默认会直接写目标值。
`to` 的第三个参数是 `EndRelation`,决定渐变结束时把值写成什么:
| 结尾参考 | 结束时的值 |
| -------------------- | --------------------------------------------------- |
| `EndRelation.Target` | 直接写成传入的目标值,默认使用这一种 |
| `EndRelation.Curve` | 结束时使用曲线终点值参考,不强制把值写成目标值 |
| `EndRelation.Self` | 正常结束时与 `Curve` 相同;提前结束时停在打断时的值 |
使用 `Curve` 时,结束值由曲线终点决定,不强制等于目标值:曲线终点回到起点附近,值也会停在起点附近;曲线终点越过目标值,值也会停在越过后的位置。
```ts
import { ref } from 'vue';
import { EndRelation } from '@motajs/animate';
// 曲线在终点只走了一半,所以 Curve 模式会停在半程
const half = (p: number) => p * 0.5;
const value = ref(0);
transition.transition(value).curve(half).to(1, 500, EndRelation.Curve);
```
下面的 live 并排比较 `Target` 与 `Curve`。曲线可以在「半程曲线」与「回程曲线」之间切换;后者到终点会回到起点,所以 `Curve` 那条也会回到起点。
<ClientOnly>
<RenderDemo :loader="endRelationLoader" :width="480" :height="320" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
## 完成等待
要让两段动画接上,调用方需要知道上一段什么时候结束;`wait` 把这段时间变成一个可等待的信号,避免用定时器猜。
`wait(animatable)` 返回该对象当前渐变的 `Promise`;对象没有活动渐变时立即兑现。它只等待传入的对象,不等待其他对象的渐变。用法顺序是:先调用 `to` 启动一段渐变,再对同一个对象 `await wait(...)`。
```ts
async function fadeTo(value: number): Promise<void> {
transition.transition(opacity).to(value, 300);
await transition.wait(opacity);
}
```
`wait` 在渐变途中被调用时,等待的是该对象当前这次渐变;如果中途又调用了 `to`,同一个 `Promise` 会在新目标完成时兑现。把多个 `to` 与 `wait` 串起来,就能写出顺序步骤:
```ts
async function runStroke() {
// 第一段:正弦曲线,400ms 走到 1
transition.transition(marker).curve(sin()).to(1, 400);
await transition.wait(marker);
// 第二段:线性曲线,900ms 回到 0
transition.transition(marker).curve(linear()).to(0, 900);
await transition.wait(marker);
}
```
第一段结束后,`wait` 才让出执行权;第二段从第一段写回的当前值继续。需要计划级等待时使用 `Animater`。
## 释放与销毁
执行器会持有选中的对象和激励源绑定;组件或动画结束时如果一直不清理,它就会继续惦记这些对象。
`revoke()` 释放当前通过 `transition` 选中的对象,避免执行器一直持有它;它不会停止已经开始的渐变。释放后,新的 `to` 需要重新用 `transition` 选择对象。清理顺序是:先 `revoke()` 放掉选中的对象,再按需重新 `transition` 选择;要停止整个执行器时再用 `destroy()`。
`destroy()` 解除激励源绑定并清理执行器;之后这个执行器不能再推进。由 `useTransition` 内部创建的执行器会在组件卸载时自动销毁;传入已有执行器时,组件卸载只解除绑定。
```ts
const transition = useTransition()!;
const opacity = ref(0);
transition.transition(opacity).to(1, 600);
// 释放选中对象:渐变继续,但之后的 to 需要重新 transition 选择
transition.revoke();
transition.transition(opacity).to(0.2, 300);
// 解除激励源绑定:之后不会再推进
transition.destroy();
```
## 与动画执行器的分工
| 项目 | `Transition` | `Animater` |
| -------- | ---------------------------- | ----------------------------------- |
| 组织单位 | 单个数值的连续渐变 | 多个动画对象与多个计划组 |
| 时序关系 | 只有当前渐变的时长 | `after`、`when`、组前等待、组后等待 |
| 典型用途 | 淡入淡出、悬停反馈、颜色过渡 | 多对象编排、分段动画、并行与延迟 |
需要「一个数慢慢变成另一个数」时用 `Transition`;需要给多个值排先后顺序、设置延迟或并行关系时,用[动画执行器](./animation-runner.md)。
<script setup>
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
const transitionLoader = () =>
import('../../.vitepress/components/demos/ui/animation-transition.tsx');
const endRelationLoader = () =>
import('../../.vitepress/components/demos/ui/animation-transition-end-relation.tsx');
</script>