AnimationManager API

大约 3 分钟

AnimationManager API

AnimationManager 是 vjmapext 的动画引擎核心，管理动画生命周期并协调帧更新。本页同时涵盖所有动画工具类。

AnimationManager

通过 mapcadLayer.animationManager 访问。

add(id, callback, options?)

注册一个动画回调。

参数	类型	说明
id	`string`	唯一标识符
callback	`AnimationCallback`	`(deltaTime: number) => void`，每帧调用
options	`AnimationItemOptions`	可选，`{ maxFps?: number }`，默认 30

mapcadLayer.animationManager.add('rotate', (dt) => {
  angle += dt * 0.001;
  entity.rotation = angle * 180 / Math.PI;
  entity.styleChanged();
}, { maxFps: 60 });

remove(id)

移除指定动画。

removeAll()

移除所有动画。

pause(id) / resume(id)

暂停/恢复指定动画。

类型

type AnimationCallback = (deltaTime: number) => void;
interface AnimationItemOptions { maxFps?: number; }

Easing 缓动函数

Easing 类提供 30 种缓动函数，每个函数签名为 (t: number) => number，t 范围 [0, 1]。

可用函数

类别	函数
线性	`easeLinear`
二次	`easeInQuad`, `easeOutQuad`, `easeInOutQuad`
三次	`easeInCubic`, `easeOutCubic`, `easeInOutCubic`
四次	`easeInQuart`, `easeOutQuart`, `easeInOutQuart`
正弦	`easeInSine`, `easeOutSine`, `easeInOutSine`
指数	`easeInExpo`, `easeOutExpo`, `easeInOutExpo`
圆形	`easeInCirc`, `easeOutCirc`, `easeInOutCirc`
回弹	`easeInBack`, `easeOutBack`, `easeInOutBack`
弹跳	`easeInBounce`, `easeOutBounce`, `easeInOutBounce`
弹性	`easeInElastic`, `easeOutElastic`, `easeInOutElastic`

const { Easing, easeOutBounce } = vjmapext;
const value = easeOutBounce(0.5); // 0~1 范围

createTween(options)

创建补间动画，在指定时间内从一个值过渡到另一个值。

TweenOptions

属性	类型	说明
from	`number`	起始值
to	`number`	结束值
duration	`number`	持续时间（毫秒）
easing	`EasingFunction`	可选，缓动函数
onUpdate	`(value: number) => void`	每帧回调
onComplete	`() => void`	可选，完成回调

返回值: { stop(): void } — 可提前停止动画。

const { createTween, easeOutCubic } = vjmapext;
const tween = createTween({
  from: 0, to: 100,
  duration: 2000,
  easing: easeOutCubic,
  onUpdate(val) { circle.radius = val; circle.changed(); },
  onComplete() { console.log('完成'); }
});

PathAnimator

沿路径移动实体的动画器。

构造函数

new PathAnimator(options: PathAnimatorOptions)

PathAnimatorOptions

属性	类型	说明
entity	`EntityBase`	要移动的实体
path	`Point2D[]`	路径点数组
duration	`number`	持续时间（毫秒）
loop	`boolean`	可选，是否循环
easing	`EasingFunction`	可选，缓动函数
onUpdate	`(progress: number) => void`	可选，进度回调
onComplete	`() => void`	可选，完成回调

方法

方法	说明
`start(animManager)`	开始动画，传入 AnimationManager
`stop()`	停止动画
`pause()`	暂停
`resume()`	恢复

TrailEffect

运动拖尾特效。

TrailEffectOptions

属性	类型	说明
entity	`EntityBase`	目标实体
maxPoints	`number`	可选，最大轨迹点数
fadeColor	`number`	可选，拖尾淡出颜色
trailWidth	`number`	可选，拖尾线宽

SpringAnimator

弹簧物理动画。

SpringOptions

属性	类型	说明
stiffness	`number`	可选，弹簧刚度
damping	`number`	可选，阻尼系数
mass	`number`	可选，质量
onUpdate	`(value: number) => void`	每帧回调
onComplete	`() => void`	可选，完成回调

KeyframeAnimator

关键帧序列动画。

类型

interface Keyframe {
  time: number;    // 0~1 归一化时间
  value: number;
  easing?: EasingFunction;
}

interface KeyframeOptions {
  keyframes: Keyframe[];
  duration: number;  // 毫秒
  loop?: boolean;
  onUpdate(value: number): void;
}

LineReveal

线条渐进绘制效果。

LineRevealOptions

属性	类型	说明
entity	`EntityBase`	目标线/多段线实体
duration	`number`	持续时间（毫秒）
easing	`EasingFunction`	可选，缓动函数

BlinkEffect

闪烁/报警效果。

BlinkEffectOptions

属性	类型	说明
entity	`EntityBase`	目标实体
onColor	`number`	亮色（hex）
offColor	`number`	暗色（hex）
interval	`number`	闪烁间隔（毫秒）
mode	`BlinkMode`	可选，`'toggle'`（开关）或 `'breath'`（呼吸灯）

颜色插值

lerpColor(color1, color2, t)

在两个颜色值之间插值。

参数	类型	说明
color1	`number`	起始颜色（如 `0xff0000`）
color2	`number`	结束颜色
t	`number`	插值因子 `[0, 1]`
返回	`number`	插值后的颜色

lerpColorHex(hex1, hex2, t)

与 lerpColor 相同，但参数和返回值为 '#rrggbb' 格式字符串。