tweens

补间动画

在 Phaser 4 中随时间对属性进行动画处理 —— TweenManager、创建补间动画、补间配置、缓动函数、补间链、交错、yoyo、重复、回调以及补间目标。

关键源路径： src/tweens/TweenManager.js、src/tweens/tween/Tween.js、src/tweens/tween/TweenChain.js、src/tweens/tween/BaseTween.js、src/tweens/builders/、src/tweens/typedefs/、src/tweens/events/、src/math/easing/ 相关技能： ../sprites-and-images/SKILL.md、../animations/SKILL.md

快速开始

// In a Scene's create() method:

const logo = this.add.image(100, 300, 'logo');

// Basic tween -- move the logo to x:600 over 2 seconds
this.tweens.add({
    targets: logo,
    x: 600,
    duration: 2000,
    ease: 'Power2'
});

this.tweens 是场景的 TweenManager 实例，在每个 Scene 中都可用。add() 方法会创建一个补间动画，将其添加到管理器中，并立即开始播放。

核心概念

补间动画生命周期

已创建 -> 活跃（onActive）-> 延迟启动（delay）-> 播放中（onStart、每帧 onUpdate）-> Yoyo/重复（onYoyo、onRepeat）-> 循环（onLoop）-> 完成（onComplete，然后自动销毁，除非设置 persist: true）。

即发即弃设计

补间动画在完成后会自动销毁。除非你之后想要控制它们，否则无需保存引用。在配置中设置 persist: true 可以让补间动画在完成后仍保持存活，以便通过 tween.play() 或 tween.restart() 重放。完成后，你必须对持久化的补间动画手动调用 tween.destroy()。

目标

targets 属性接受单个对象、对象数组或返回其中任意一个的函数。目标通常是 Game Object，但也可以是任何具有数值属性的 JavaScript 对象。补间动画不会操作任何以下划线开头的属性。

// Single target
this.tweens.add({ targets: sprite, alpha: 0, duration: 500 });

// Multiple targets
this.tweens.add({ targets: [sprite1, sprite2, sprite3], y: 100, duration: 1000 });

属性值

this.tweens.add({
    targets: sprite,
    x: 400,                  // absolute value
    y: '-=100',              // relative (subtract 100 from current)
    rotation: '+=3.14',      // relative (add to current)
    alpha: { value: 0, duration: 300, ease: 'Cubic.easeIn' },  // per-property config
    scale: [0.5, 1.5, 1],   // array: interpolates through values over duration
    angle: function (target, key, value, targetIndex, totalTargets, tween) {
        return targetIndex * 90;   // function: called once per target
    },
    duration: 1000
});

数组值默认使用线性插值；可通过 interpolation 配置覆盖（'linear'、'bezier'、'catmull'）。

常见模式

基础补间动画

this.tweens.add({
    targets: this.player,
    x: 500,
    y: 300,
    duration: 1000,
    ease: 'Sine.easeInOut'
});

多属性与逐属性配置

this.tweens.add({
    targets: this.enemy,
    x: { value: 600, duration: 1500, ease: 'Bounce.easeOut' },
    y: { value: 200, duration: 1000, ease: 'Power2' },
    alpha: { value: 0.5, duration: 500, delay: 1000 }
});

Yoyo 与重复

this.tweens.add({
    targets: this.coin,
    y: '-=50',
    duration: 600,
    ease: 'Sine.easeInOut',
    yoyo: true,         // returns to start value after reaching end
    hold: 200,          // pause 200ms at the end value before yoyo-ing back
    repeat: -1,         // -1 = infinite, 0 = play once, 1 = play twice, etc.
    repeatDelay: 300     // pause 300ms before each repeat
});

repeat 控制每个属性额外播放多少次。repeat 为 1 表示该补间动画总共播放两次。loop 属性（位于 BaseTween 上）会从头重新开始整个补间动画，包括所有属性。使用 repeat 进行属性级循环，使用 loop 进行补间动画级循环。

交错

交错通过 this.tweens.stagger() 在多个目标之间偏移一个值：

// 100ms delay between each target
delay: this.tweens.stagger(100)

// From center outward
delay: this.tweens.stagger(200, { from: 'center' })

// Range: distribute 0-1000ms across targets
delay: this.tweens.stagger([0, 1000])

// Grid stagger with easing
delay: this.tweens.stagger(500, { grid: [10, 6], from: 'center', ease: 'Cubic.easeOut' })

StaggerConfig： start（偏移）、ease（字符串/函数）、from（'first'/'center'/'last'/索引）、grid（[宽, 高]）。

补间链

TweenChain 按顺序播放补间动画。链中的每个补间动画在前一个完成后开始：

this.tweens.chain({
    targets: this.player,
    tweens: [
        { x: 300, duration: 1000, ease: 'Power2' },
        { y: 500, duration: 800, ease: 'Bounce.easeOut' },
        { scale: 2, duration: 500 },
        { alpha: 0, duration: 400 }
    ],
    loop: 1,          // loop the entire chain once (plays twice total)
    loopDelay: 500,
    onComplete: function () {
        console.log('Chain finished');
    }
});

tweens 中的每个条目都是一个标准的 TweenBuilderConfig。链级配置支持 loop、loopDelay、completeDelay、paused、persist 以及链级回调。逐补间动画回调（onUpdate、onRepeat、onYoyo）归属于各个条目。使用 chain.add(tweenConfigs) 动态追加。

相对值

this.tweens.add({
    targets: sprite,
    x: '+=200',    // add 200 to current x
    y: '-=50',     // subtract 50 from current y
    angle: '+=180',
    duration: 1000
});

回调与事件

this.tweens.add({
    targets: sprite,
    x: 600,
    duration: 2000,

    // All callbacks receive (tween, targets, ...params)
    onStart: function (tween, targets) { },
    onUpdate: function (tween, targets) { },     // per-property, per-target, per-frame
    onYoyo: function (tween, targets) { },
    onRepeat: function (tween, targets) { },
    onLoop: function (tween, targets) { },
    onComplete: function (tween, targets) { },

    onCompleteParams: ['extra', 'args'],
    callbackScope: this
});

// Set callback after creation
tween.setCallback('onComplete', function (tween, targets) { }, []);

// Event emitter style (tweens extend EventEmitter)
tween.on('complete', function (tween, targets) { });

数字补间动画

数字补间动画没有目标对象。它在两个数值之间进行补间：

const counter = this.tweens.addCounter({
    from: 0,
    to: 100,
    duration: 2000,
    ease: 'Linear',
    onUpdate: function (tween) {
        const value = tween.getValue();
        console.log(value);   // 0 ... 100
    }
});

控制与终止补间动画

const tween = this.tweens.add({ targets: sprite, x: 600, duration: 2000, persist: true });

// Playback control
tween.pause();                  tween.resume();
tween.stop();                   // flags for removal; fires onStop
tween.restart();                // reset and replay from beginning
tween.seek(1000);               // seek to 1000ms (suppresses events by default)
tween.complete();               // immediately complete; fires onComplete
tween.completeAfterLoop(0);     // finish after current loop
tween.forward(500);             tween.rewind(500);
tween.setTimeScale(0.5);       // per-tween speed
tween.updateTo('x', 800);      // change end value mid-tween

// Manager-level control
this.tweens.killAll();                     // destroy all tweens
this.tweens.killTweensOf(sprite);          // destroy tweens on target
this.tweens.isTweening(sprite);            // boolean check
this.tweens.pauseAll();                    this.tweens.resumeAll();
this.tweens.setGlobalTimeScale(0.5);       // global speed

配置参考

TweenBuilderConfig

属性	类型	默认值	描述
targets	any / any[]	（必填）	要补间的对象。
duration	number	1000	持续时间，单位为 ms。
delay	number / function	0	开始前的延迟（ms）。接受 stagger()。
ease	string / function	'Power0'	缓动函数名称或自定义函数。
easeParams	array	null	参数化缓动的参数（例如 Elastic）。
hold	number	0	在 yoyo 之前于结束值处保持的时间（ms）。
repeat	number	0	每个属性的重复次数。-1 = 无限。
repeatDelay	number	0	每次重复前的延迟（ms）。
yoyo	boolean	false	到达结束值后反向回到起始值。
flipX / flipY	boolean	false	在 yoyo/repeat 时切换翻转。
loop	number	0	补间级别的循环次数。-1 = 无限。
loopDelay	number	0	每次循环前的延迟（ms）。
completeDelay	number	0	触发 onComplete 前的延迟（ms）。
paused	boolean	false	以暂停状态开始。调用 play() 开始。
persist	boolean	false	完成后保持存活。
props	object	--	显式属性配置映射（替代顶层属性）。
interpolation	string / function	--	用于数组值：'linear'、'bezier'、'catmull'。
callbackScope	any	tween	回调的 this 上下文。
回调	function	--	onActive、onStart、onUpdate、onYoyo、onRepeat、onLoop、onComplete、onStop、onPause、onResume。每个都有匹配的 on<Name>Params 数组。

TweenChainBuilderConfig

属性	类型	默认值	描述
targets	any / any[]	--	由子补间继承的默认目标。
tweens	TweenBuilderConfig[]	（必填）	要按顺序播放的补间配置数组。
loop	number	0	整个链的循环次数。-1 = 无限。
loopDelay	number	0	每次循环前的延迟（ms）。
completeDelay	number	0	触发 onComplete 前的延迟（ms）。
paused	boolean	false	以暂停状态开始。
persist	boolean	false	完成后保持存活。
回调	function	--	onActive、onStart、onLoop、onComplete、onStop、onPause、onResume。

NumberTweenBuilderConfig

属性	类型	默认值	描述
from	number	0	起始值。
to	number	1	结束值。
duration	number	1000	持续时间，单位为 ms。
ease	string / function	'Power0'	缓动函数。
所有标准时间选项	--	--	delay、hold、repeat、repeatDelay、yoyo、loop、loopDelay、completeDelay、paused、persist。
所有标准回调	--	--	与 TweenBuilderConfig 相同的回调集合。

TweenPropConfig（逐属性对象）

当属性值是对象而不是数字/字符串时使用。支持：value、getActive、getEnd、getStart、ease、delay、duration、yoyo、hold、repeat、repeatDelay、flipX、flipY、interpolation。所有这些都会针对该单个属性覆盖补间级别的默认值。

缓动函数

所有缓动名称均不区分大小写。在 ease 配置属性中使用字符串名称。

Power 别名

名称	等效项
Power0	Linear
Power1	Quad.easeOut（Quadratic Out）
Power2	Cubic.easeOut
Power3	Quart.easeOut（Quartic Out）
Power4	Quint.easeOut（Quintic Out）

完整缓动列表

每种类型都支持 .easeIn、.easeOut、.easeInOut 变体。裸名称默认为 Out。

类型： Quad、Cubic、Quart、Quint、Sine、Expo、Circ、Elastic、Back、Bounce。

用法： 'Sine.easeInOut'、'Bounce.easeIn'、'Cubic.easeOut'、'Back'（与 'Back.easeOut' 相同）。

特殊： Linear（无缓动）、Stepped（离散步进 -- easeParams: [numSteps]）。

自定义： ease: function (t) { return t * t; }，其中 t 为 0 到 1。

事件

Tween（以及 TweenChain）继承自 EventEmitter。你可以通过 .on() 监听：

事件字符串	常量	触发时机
'active'	Phaser.Tweens.Events.TWEEN_ACTIVE	Tween 被添加到管理器
'start'	Phaser.Tweens.Events.TWEEN_START	播放开始（延迟之后）
'update'	Phaser.Tweens.Events.TWEEN_UPDATE	每帧更新属性值
'yoyo'	Phaser.Tweens.Events.TWEEN_YOYO	属性开始 yoyo 回退
'repeat'	Phaser.Tweens.Events.TWEEN_REPEAT	属性重复
'loop'	Phaser.Tweens.Events.TWEEN_LOOP	整个 Tween 循环
'complete'	Phaser.Tweens.Events.TWEEN_COMPLETE	Tween 完成
'stop'	Phaser.Tweens.Events.TWEEN_STOP	调用了 tween.stop()
'pause'	Phaser.Tweens.Events.TWEEN_PAUSE	调用了 tween.pause()
'resume'	Phaser.Tweens.Events.TWEEN_RESUME	调用了 tween.resume()

Tween 事件的事件监听器签名：function(tween, targets)。在跳转（tween.isSeeking === true）期间，事件和回调默认会被抑制。

API 快速参考

TweenManager (this.tweens)

方法	返回值	用途
add(config)	Tween	创建、添加并启动一个 Tween。
addMultiple(configs[])	Tween[]	一次性创建多个 Tween。
create(config)	Tween	创建但不添加。稍后用 existing() 添加。
chain(config)	TweenChain	创建并启动一个顺序链。
addCounter(config)	Tween	数值 Tween（无目标）。
stagger(value, config?)	function	用于 delay/属性值的 stagger 函数。
existing(tween)	this	将预先创建的 Tween 添加到管理器。
remove(tween)	this	移除但不销毁。
has(tween)	boolean	检查 Tween 是否在管理器中。
getTweens()	Tween[]	所有活动中的 Tween（副本）。
getTweensOf(target)	Tween[]	影响某个目标的 Tween。
isTweening(target)	boolean	目标是否正在被 Tween？
killAll() / killTweensOf(target)	this	销毁 Tween。
pauseAll() / resumeAll()	this	暂停/恢复所有 Tween。
setGlobalTimeScale(v) / getGlobalTimeScale()	this / number	全局速度。
setFps(fps)	this	限制 tick 频率（默认 240）。
setLagSmooth(limit, skip)	this	配置卡顿平滑。
each(cb, scope)	this	遍历所有 Tween。

Tween 实例

方法	用途
play() / pause() / resume()	播放控制。
stop()	停止并标记为待移除。触发 onStop。
restart()	重置并重新播放。
complete(delay?)	立即完成。
completeAfterLoop(loops?)	再循环 N 次后完成。
seek(ms, delta?, emit?)	跳转到 ms 偏移位置。
forward(ms) / rewind(ms)	向前/向后步进。
setTimeScale(v) / getTimeScale()	每个 Tween 的速度。
setCallback(type, fn, params?)	创建后设置回调。
getValue(index?)	当前 TweenData 的值。
updateTo(key, value, startToCurrent?)	在 Tween 过程中更改结束值。
hasTarget(target) / isPlaying() / isPaused()	状态检查。
remove() / destroy()	清理。

关键属性：targets、duration、elapsed、progress（0-1）、totalProgress（0-1，包含循环）、totalDuration、timeScale、paused、persist、data（TweenData[]）、isInfinite、isNumberTween。

TweenChain 实例

继承自 BaseTween。拥有所有 Tween 播放方法（play、pause、resume、stop、restart、complete 等），外加 add(tweenConfigs) 用于动态追加 Tween。属性：currentTween、currentIndex。

注意事项

• 以下划线开头的属性会被忽略。 补间会跳过任何名称以 _ 开头的属性。
• 补间会自动销毁。 如果你保存了补间的引用并在其完成后尝试使用，它可能已被销毁。设置 persist: true 可使其保持存活，但完成后你必须自行调用 destroy()。
• repeat 与 loop。 repeat 是针对单个属性的（位于 TweenData 上）。loop 会重新开始整个补间。repeat 为 1 表示该属性总共播放两次。
• loop: -1 意味着 onComplete 永远不会触发。 无限循环的补间永远不会完成。请使用 completeAfterLoop() 来优雅地结束它。
• 跳转（seeking）会抑制事件。 调用 tween.seek() 时，除非你将 true 作为第三个参数传入，否则事件和回调不会被派发。
• 交错（stagger）仅在多个目标时生效。 在单目标补间上使用 this.tweens.stagger() 不会产生可见的交错效果。
• 已销毁的目标。 如果补间的目标将 isDestroyed 设为 true，补间会提前完成。在销毁补间所引用的对象之前，请始终先清理补间，或依赖此自动检查。
• TweenManager.timeScale 与 Tween.timeScale 相乘。 有效速度为 managerTimeScale * tweenTimeScale。将任一者设为 0 都会冻结补间。
• 持续时间不能为零。 内部会将其限制为最小 0.01ms。
• TweenChain 的 targets 会被继承。 如果你在链级别设置 targets，链中的各个补间会继承它们，除非它们指定了自己的 targets。

源文件映射

文件	用途
src/tweens/TweenManager.js	场景插件。add、chain、stagger、killAll 等。
src/tweens/tween/Tween.js	单个补间。目标、TweenData 数组、跳转、更新。
src/tweens/tween/TweenChain.js	通过有序的子 Tween 进行顺序补间播放。
src/tweens/tween/BaseTween.js	共享基类。EventEmitter、回调、状态机。
src/tweens/tween/BaseTweenData.js	每个属性的状态：持续时间、延迟、yoyo、repeat、进度。
src/tweens/tween/TweenData.js	数值属性补间（继承自 BaseTweenData）。
src/tweens/tween/TweenFrameData.js	纹理帧补间（继承自 BaseTweenData）。
src/tweens/builders/TweenBuilder.js	将配置解析为 Tween 实例。
src/tweens/builders/TweenChainBuilder.js	将配置解析为 TweenChain 实例。
src/tweens/builders/NumberTweenBuilder.js	构建无目标的数值补间。
src/tweens/builders/StaggerBuilder.js	创建交错函数。
src/tweens/events/	事件常量（TWEEN_ACTIVE、TWEEN_START 等）。
src/tweens/typedefs/	所有配置对象的 JSDoc 类型定义。
src/math/easing/EaseMap.js	将缓动字符串名称映射到函数。