Back to Details

tweens

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tweens

补间动画

Animating properties over time in Phaser 4 -- TweenManager, creating tweens, tween config, easing functions, tween chains, stagger, yoyo, repeat, callbacks, and tween targets.
Key source paths: 
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/
Related skills: ../sprites-and-images/SKILL.md, ../animations/SKILL.md
在Phaser 4中为属性制作随时间变化的动画——TweenManager、创建补间、补间配置、缓动函数、补间链、交错动画、往返动画、重复、回调以及补间目标。
关键源码路径: 
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

Quick Start

快速开始

js
// 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
is the scene's 
TweenManager
instance, available in every Scene. The 
add()
method creates a tween, adds it to the manager, and starts playback immediately.
js
// 在场景的create()方法中:

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

// 基础补间——在2秒内将logo移动到x:600位置
this.tweens.add({
    targets: logo,
    x: 600,
    duration: 2000,
    ease: 'Power2'
});
this.tweens
是场景的
TweenManager
实例，每个场景中都可调用。
add()
方法会创建一个补间，将其添加到管理器中，并立即开始播放。

Core Concepts

核心概念

Tween Lifecycle

补间生命周期

Created -> Active (
onActive
) -> Start Delayed (
delay
) -> Playing (
onStart
, 
onUpdate
per frame) -> Yoyo/Repeat (
onYoyo
, 
onRepeat
) -> Loop (
onLoop
) -> Complete (
onComplete
, then auto-destroyed unless 
persist: true
).
创建 -> 激活（
onActive
） -> 延迟启动（
delay
） -> 播放中（
onStart
，每帧触发
onUpdate
） -> 往返/重复（
onYoyo
、
onRepeat
） -> 循环（
onLoop
） -> 完成（
onComplete
，除非设置
persist: true
，否则会自动销毁）。

Fire-and-Forget Design

"即开即忘"设计

Tweens auto-destroy after completion. You do not need to store a reference unless you want to control them later. Set 
persist: true
in the config to keep a tween alive after completion for replay via 
tween.play()
or 
tween.restart()
. You must manually call 
tween.destroy()
on persisted tweens when done.
补间完成后会自动销毁。除非你之后需要控制它，否则无需存储引用。若要在补间完成后保留它以便通过
tween.play()
或
tween.restart()
重播，请在配置中设置
persist: true
。对于持久化的补间，使用完毕后必须手动调用
tween.destroy()
。

Targets

目标对象

The 
targets
property accepts a single object, an array of objects, or a function that returns either. Targets are typically Game Objects but can be any JavaScript object with numeric properties. A tween will not manipulate any property that begins with an underscore.
js
// Single target
this.tweens.add({ targets: sprite, alpha: 0, duration: 500 });

// Multiple targets
this.tweens.add({ targets: [sprite1, sprite2, sprite3], y: 100, duration: 1000 });
targets
属性接受单个对象、对象数组，或返回这两者之一的函数。目标对象通常是游戏对象，但也可以是任何带有数值属性的JavaScript对象。补间不会操作任何以下划线开头的属性。
js
// 单个目标
this.tweens.add({ targets: sprite, alpha: 0, duration: 500 });

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

Property Values

属性值

js
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
});
Array values use linear interpolation by default; override with the 
interpolation
config (
'linear'
, 
'bezier'
, 
'catmull'
).
js
this.tweens.add({
    targets: sprite,
    x: 400,                  // 绝对值
    y: '-=100',              // 相对值（从当前值减去100）
    rotation: '+=3.14',      // 相对值（加到当前值上）
    alpha: { value: 0, duration: 300, ease: 'Cubic.easeIn' },  // 单属性配置
    scale: [0.5, 1.5, 1],   // 数组：在持续时间内插值遍历这些值
    angle: function (target, key, value, targetIndex, totalTargets, tween) {
        return targetIndex * 90;   // 函数：每个目标调用一次
    },
    duration: 1000
});
数组值默认使用线性插值；可通过
interpolation
配置项覆盖（可选值：
'linear'
、
'bezier'
、
'catmull'
）。

Common Patterns

常见模式

Basic Tween

基础补间

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

Multiple Properties with Per-Property Config

多属性与单属性配置

js
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 }
});
js
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 and Repeat

往返与重复

js
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
controls how many extra times each property plays. A 
repeat
of 1 means the tween plays twice total. The 
loop
property (on 
BaseTween
) restarts the entire tween from scratch, including all properties. Use 
repeat
for property-level looping and 
loop
for tween-level looping.
js
this.tweens.add({
    targets: this.coin,
    y: '-=50',
    duration: 600,
    ease: 'Sine.easeInOut',
    yoyo: true,         // 到达结束值后返回起始值
    hold: 200,          // 在结束值处暂停200毫秒后再往返
    repeat: -1,         // -1 = 无限重复，0 = 播放一次，1 = 播放两次，以此类推
    repeatDelay: 300     // 每次重复前暂停300毫秒
});
repeat
控制每个属性额外播放的次数。
repeat
为1意味着补间总共播放两次。
loop
属性（属于
BaseTween
）会从头重启整个补间，包括所有属性。属性级循环使用
repeat
，补间级循环使用
loop
。

Stagger

交错动画

Stagger offsets a value across multiple targets via 
this.tweens.stagger()
:
js
// 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
(offset), 
ease
(string/function), 
from
(
'first'
/
'center'
/
'last'
/index), 
grid
([w, h]).
通过
this.tweens.stagger()
可在多个目标间偏移值：
js
// 每个目标之间延迟100毫秒
delay: this.tweens.stagger(100)

// 从中心向外扩散
delay: this.tweens.stagger(200, { from: 'center' })

// 范围：在目标间分配0-1000毫秒的延迟
delay: this.tweens.stagger([0, 1000])

// 带缓动的网格交错
delay: this.tweens.stagger(500, { grid: [10, 6], from: 'center', ease: 'Cubic.easeOut' })
StaggerConfig配置项: 
start
（偏移量）、
ease
（字符串/函数）、
from
（
'first'
/
'center'
/
'last'
/索引）、
grid
（[宽, 高]）。

Tween Chain

补间链

A 
TweenChain
plays tweens in sequence. Each tween in the chain starts after the previous one completes:
js
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');
    }
});
Each entry in 
tweens
is a standard 
TweenBuilderConfig
. Chain-level config supports 
loop
, 
loopDelay
, 
completeDelay
, 
paused
, 
persist
, and chain-level callbacks. Per-tween callbacks (
onUpdate
, 
onRepeat
, 
onYoyo
) belong on individual entries. Use 
chain.add(tweenConfigs)
to append dynamically.
TweenChain
会按顺序播放补间。链中的每个补间会在前一个补间完成后开始：
js
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,          // 整个链循环一次（总共播放两次）
    loopDelay: 500,
    onComplete: function () {
        console.log('链播放完成');
    }
});
tweens
中的每个条目都是标准的
TweenBuilderConfig
。链级配置支持
loop
、
loopDelay
、
completeDelay
、
paused
、
persist
以及链级回调。单补间回调（
onUpdate
、
onRepeat
、
onYoyo
）需放在各个条目上。使用
chain.add(tweenConfigs)
可动态追加补间。

Relative Values

相对值

js
this.tweens.add({
    targets: sprite,
    x: '+=200',    // add 200 to current x
    y: '-=50',     // subtract 50 from current y
    angle: '+=180',
    duration: 1000
});
js
this.tweens.add({
    targets: sprite,
    x: '+=200',    // 在当前x值基础上加200
    y: '-=50',     // 在当前y值基础上减50
    angle: '+=180',
    duration: 1000
});

Callbacks and Events

回调与事件

js
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) { });
js
this.tweens.add({
    targets: sprite,
    x: 600,
    duration: 2000,

    // 所有回调都会接收参数(tween, targets, ...params)
    onStart: function (tween, targets) { },
    onUpdate: function (tween, targets) { },     // 每帧、每个属性、每个目标触发
    onYoyo: function (tween, targets) { },
    onRepeat: function (tween, targets) { },
    onLoop: function (tween, targets) { },
    onComplete: function (tween, targets) { },

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

// 创建后设置回调
tween.setCallback('onComplete', function (tween, targets) { }, []);

// 事件发射器风格（补间继承自EventEmitter）
tween.on('complete', function (tween, targets) { });

Number Tweens

数值补间

A Number Tween has no target object. It tweens between two numeric values:
js
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
    }
});
数值补间没有目标对象，它在两个数值之间进行补间：
js
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
    }
});

Controlling and Killing Tweens

控制与销毁补间

js
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
js
const tween = this.tweens.add({ targets: sprite, x: 600, duration: 2000, persist: true });

// 播放控制
tween.pause();                  tween.resume();
tween.stop();                   // 标记为待移除；触发onStop
tween.restart();                // 重置并从头重播
tween.seek(1000);               // 跳转到1000毫秒位置（默认抑制事件）
tween.complete();               // 立即完成；触发onComplete
tween.completeAfterLoop(0);     // 当前循环结束后完成
tween.forward(500);             tween.rewind(500);
tween.setTimeScale(0.5);       // 单个补间的播放速度
tween.updateTo('x', 800);      // 补间播放中修改结束值

// 管理器级控制
this.tweens.killAll();                     // 销毁所有补间
this.tweens.killTweensOf(sprite);          // 销毁目标对象上的补间
this.tweens.isTweening(sprite);            // 布尔值检查
this.tweens.pauseAll();                    this.tweens.resumeAll();
this.tweens.setGlobalTimeScale(0.5);       // 全局播放速度

Configuration Reference

配置参考

TweenBuilderConfig

TweenBuilderConfig

PropertyTypeDefaultDescription
targets
any / any[](required)Object(s) to tween.
duration
number
1000
Duration in ms.
delay
number / function
0
Delay before start (ms). Accepts 
stagger()
.
ease
string / function
'Power0'
Easing function name or custom function.
easeParams
array
null
Parameters for parameterized easing (e.g. Elastic).
hold
number
0
Hold at end value before yoyo (ms).
repeat
number
0
Per-property repeat count. 
-1
= infinite.
repeatDelay
number
0
Delay before each repeat (ms).
yoyo
boolean
false
Reverse back to start after reaching end.
flipX
/ 
flipY
boolean
false
Toggle flip on yoyo/repeat.
loop
number
0
Tween-level loop count. 
-1
= infinite.
loopDelay
number
0
Delay before each loop (ms).
completeDelay
number
0
Delay before 
onComplete
fires (ms).
paused
boolean
false
Start paused. Call 
play()
to begin.
persist
boolean
false
Keep alive after completion.
props
object--Explicit property config map (alt to top-level props).
interpolation
string / function--For array values: 
'linear'
, 
'bezier'
, 
'catmull'
.
callbackScope
anytween
this
context for callbacks.
Callbacksfunction--
onActive
, 
onStart
, 
onUpdate
, 
onYoyo
, 
onRepeat
, 
onLoop
, 
onComplete
, 
onStop
, 
onPause
, 
onResume
. Each has matching 
on<Name>Params
array.
PropertyTypeDefaultDescription
targets
any / any[](必填)要补间的对象。
duration
number
1000
持续时间（毫秒）。
delay
number / function
0
启动前的延迟（毫秒）。支持
stagger()
。
ease
string / function
'Power0'
缓动函数名称或自定义函数。
easeParams
array
null
参数化缓动的参数（例如Elastic）。
hold
number
0
往返前在结束值处停留的时间（毫秒）。
repeat
number
0
单属性重复次数。
-1
= 无限重复。
repeatDelay
number
0
每次重复前的延迟（毫秒）。
yoyo
boolean
false
到达结束值后反向回到起始值。
flipX
/ 
flipY
boolean
false
在往返/重复时切换翻转状态。
loop
number
0
补间级循环次数。
-1
= 无限循环。
loopDelay
number
0
每次循环前的延迟（毫秒）。
completeDelay
number
0
onComplete
触发前的延迟（毫秒）。
paused
boolean
false
启动时处于暂停状态。调用
play()
开始播放。
persist
boolean
false
完成后保持存活状态。
props
object--显式的属性配置映射（替代顶层属性）。
interpolation
string / function--针对数组值：
'linear'
、
'bezier'
、
'catmull'
。
callbackScope
anytween回调函数的
this
上下文。
Callbacksfunction--
onActive
、
onStart
、
onUpdate
、
onYoyo
、
onRepeat
、
onLoop
、
onComplete
、
onStop
、
onPause
、
onResume
。每个回调都有对应的
on<Name>Params
数组。

TweenChainBuilderConfig

TweenChainBuilderConfig

PropertyTypeDefaultDescription
targets
any / any[]--Default targets inherited by child tweens.
tweens
TweenBuilderConfig[](required)Array of tween configs to play in sequence.
loop
number
0
Times to loop the entire chain. 
-1
= infinite.
loopDelay
number
0
Delay before each loop (ms).
completeDelay
number
0
Delay before 
onComplete
fires (ms).
paused
boolean
false
Start paused.
persist
boolean
false
Keep alive after completion.
Callbacksfunction--
onActive
, 
onStart
, 
onLoop
, 
onComplete
, 
onStop
, 
onPause
, 
onResume
.
PropertyTypeDefaultDescription
targets
any / any[]--子补间继承的默认目标对象。
tweens
TweenBuilderConfig[](必填)要按顺序播放的补间配置数组。
loop
number
0
整个链的循环次数。
-1
= 无限循环。
loopDelay
number
0
每次循环前的延迟（毫秒）。
completeDelay
number
0
onComplete
触发前的延迟（毫秒）。
paused
boolean
false
启动时处于暂停状态。
persist
boolean
false
完成后保持存活状态。
Callbacksfunction--
onActive
、
onStart
、
onLoop
、
onComplete
、
onStop
、
onPause
、
onResume
。

NumberTweenBuilderConfig

NumberTweenBuilderConfig

PropertyTypeDefaultDescription
from
number
0
Start value.
to
number
1
End value.
duration
number
1000
Duration in ms.
ease
string / function
'Power0'
Easing function.
All standard timing----
delay
, 
hold
, 
repeat
, 
repeatDelay
, 
yoyo
, 
loop
, 
loopDelay
, 
completeDelay
, 
paused
, 
persist
.
All standard callbacks----Same callback set as TweenBuilderConfig.
PropertyTypeDefaultDescription
from
number
0
起始值。
to
number
1
结束值。
duration
number
1000
持续时间（毫秒）。
ease
string / function
'Power0'
缓动函数。
所有标准时序配置----
delay
、
hold
、
repeat
、
repeatDelay
、
yoyo
、
loop
、
loopDelay
、
completeDelay
、
paused
、
persist
。
所有标准回调----与TweenBuilderConfig相同的回调集合。

TweenPropConfig (Per-Property Object)

TweenPropConfig（单属性对象）

Used when a property value is an object instead of a number/string. Supports: 
value
, 
getActive
, 
getEnd
, 
getStart
, 
ease
, 
delay
, 
duration
, 
yoyo
, 
hold
, 
repeat
, 
repeatDelay
, 
flipX
, 
flipY
, 
interpolation
. All override the tween-level defaults for that one property.
当属性值为对象而非数字/字符串时使用。支持：
value
、
getActive
、
getEnd
、
getStart
、
ease
、
delay
、
duration
、
yoyo
、
hold
、
repeat
、
repeatDelay
、
flipX
、
flipY
、
interpolation
。所有配置都会覆盖该属性对应的补间级默认值。

Easing Functions

缓动函数

All easing names are case-insensitive. Use the string name in the 
ease
config property.
所有缓动函数名称不区分大小写。在
ease
配置属性中使用字符串名称即可。

Power Aliases

功率别名

NameEquivalent
Power0
Linear
Power1
Quad.easeOut
(Quadratic Out)
Power2
Cubic.easeOut
Power3
Quart.easeOut
(Quartic Out)
Power4
Quint.easeOut
(Quintic Out)
NameEquivalent
Power0
Linear
Power1
Quad.easeOut
（二次方缓出）
Power2
Cubic.easeOut
Power3
Quart.easeOut
（四次方缓出）
Power4
Quint.easeOut
（五次方缓出）

Full Easing List

完整缓动列表

Each type supports 
.easeIn
, 
.easeOut
, 
.easeInOut
variants. The bare name defaults to Out.
Types: 
Quad
, 
Cubic
, 
Quart
, 
Quint
, 
Sine
, 
Expo
, 
Circ
, 
Elastic
, 
Back
, 
Bounce
.
Usage: 
'Sine.easeInOut'
, 
'Bounce.easeIn'
, 
'Cubic.easeOut'
, 
'Back'
(same as 
'Back.easeOut'
).
Special: 
Linear
(no easing), 
Stepped
(discrete steps -- 
easeParams: [numSteps]
).
Custom: 
ease: function (t) { return t * t; }
where 
t
is 0 to 1.
每种类型都支持
.easeIn
、
.easeOut
、
.easeInOut
变体。仅使用类型名称时默认使用缓出效果。
类型: 
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。

Events

事件

Tweens (and TweenChains) extend 
EventEmitter
. You can listen via 
.on()
:
Event StringConstantFires When
'active'
Phaser.Tweens.Events.TWEEN_ACTIVE
Tween added to manager
'start'
Phaser.Tweens.Events.TWEEN_START
Playback begins (after delay)
'update'
Phaser.Tweens.Events.TWEEN_UPDATE
Property updates each frame
'yoyo'
Phaser.Tweens.Events.TWEEN_YOYO
Property begins yoyo-ing back
'repeat'
Phaser.Tweens.Events.TWEEN_REPEAT
Property repeats
'loop'
Phaser.Tweens.Events.TWEEN_LOOP
Entire tween loops
'complete'
Phaser.Tweens.Events.TWEEN_COMPLETE
Tween finishes
'stop'
Phaser.Tweens.Events.TWEEN_STOP
tween.stop()
called
'pause'
Phaser.Tweens.Events.TWEEN_PAUSE
tween.pause()
called
'resume'
Phaser.Tweens.Events.TWEEN_RESUME
tween.resume()
called
Event listener signature for Tween events: 
function(tween, targets)
. During seeking (
tween.isSeeking === true
), events and callbacks are suppressed by default.
补间（以及补间链）继承自
EventEmitter
。你可以通过
.on()
监听事件：
Event StringConstantFires When
'active'
Phaser.Tweens.Events.TWEEN_ACTIVE
补间被添加到管理器时
'start'
Phaser.Tweens.Events.TWEEN_START
播放开始时（延迟结束后）
'update'
Phaser.Tweens.Events.TWEEN_UPDATE
属性每帧更新时
'yoyo'
Phaser.Tweens.Events.TWEEN_YOYO
属性开始往返时
'repeat'
Phaser.Tweens.Events.TWEEN_REPEAT
属性重复时
'loop'
Phaser.Tweens.Events.TWEEN_LOOP
整个补间循环时
'complete'
Phaser.Tweens.Events.TWEEN_COMPLETE
补间完成时
'stop'
Phaser.Tweens.Events.TWEEN_STOP
调用
tween.stop()
时
'pause'
Phaser.Tweens.Events.TWEEN_PAUSE
调用
tween.pause()
时
'resume'
Phaser.Tweens.Events.TWEEN_RESUME
调用
tween.resume()
时
补间事件的监听器签名：
function(tween, targets)
。在跳转播放位置时（
tween.isSeeking === true
），默认会抑制事件和回调。

API Quick Reference

API速查手册

TweenManager (
this.tweens
)

TweenManager（
this.tweens
）

MethodReturnsPurpose
add(config)
Tween
Create, add, and start a tween.
addMultiple(configs[])
Tween[]
Create multiple tweens at once.
create(config)
Tween
Create without adding. Use 
existing()
to add later.
chain(config)
TweenChain
Create and start a sequential chain.
addCounter(config)
Tween
Number tween (no target).
stagger(value, config?)
function
Stagger function for delay/property values.
existing(tween)
this
Add a pre-created tween to the manager.
remove(tween)
this
Remove without destroying.
has(tween)
boolean
Check if tween is in manager.
getTweens()
Tween[]
All active tweens (copy).
getTweensOf(target)
Tween[]
Tweens affecting a target.
isTweening(target)
boolean
Is target being tweened?
killAll()
/ 
killTweensOf(target)
this
Destroy tweens.
pauseAll()
/ 
resumeAll()
this
Pause/resume all tweens.
setGlobalTimeScale(v)
/ 
getGlobalTimeScale()
this
/ 
number
Global speed.
setFps(fps)
this
Limit tick rate (default 240).
setLagSmooth(limit, skip)
this
Configure lag smoothing.
each(cb, scope)
this
Iterate all tweens.
MethodReturnsPurpose
add(config)
Tween
创建、添加并启动一个补间。
addMultiple(configs[])
Tween[]
一次性创建多个补间。
create(config)
Tween
创建补间但不添加到管理器。之后使用
existing()
添加。
chain(config)
TweenChain
创建并启动一个顺序播放的补间链。
addCounter(config)
Tween
数值补间（无目标对象）。
stagger(value, config?)
function
用于延迟/属性值的交错函数。
existing(tween)
this
将预创建的补间添加到管理器。
remove(tween)
this
移除补间但不销毁。
has(tween)
boolean
检查补间是否在管理器中。
getTweens()
Tween[]
所有活跃补间的副本。
getTweensOf(target)
Tween[]
影响目标对象的补间。
isTweening(target)
boolean
目标对象是否正在被补间？
killAll()
/ 
killTweensOf(target)
this
销毁补间。
pauseAll()
/ 
resumeAll()
this
暂停/恢复所有补间。
setGlobalTimeScale(v)
/ 
getGlobalTimeScale()
this
/ 
number
设置/获取全局播放速度。
setFps(fps)
this
限制帧率（默认240）。
setLagSmooth(limit, skip)
this
配置延迟平滑处理。
each(cb, scope)
this
遍历所有补间。

Tween Instance

补间实例

MethodPurpose
play()
/ 
pause()
/ 
resume()
Playback control.
stop()
Stop and flag for removal. Fires 
onStop
.
restart()
Reset and replay.
complete(delay?)
Immediately complete.
completeAfterLoop(loops?)
Complete after N more loops.
seek(ms, delta?, emit?)
Seek to ms offset.
forward(ms)
/ 
rewind(ms)
Step forward/back.
setTimeScale(v)
/ 
getTimeScale()
Per-tween speed.
setCallback(type, fn, params?)
Set callback after creation.
getValue(index?)
Current TweenData value.
updateTo(key, value, startToCurrent?)
Change end value mid-tween.
hasTarget(target)
/ 
isPlaying()
/ 
isPaused()
State checks.
remove()
/ 
destroy()
Cleanup.
Key properties: 
targets
, 
duration
, 
elapsed
, 
progress
(0-1), 
totalProgress
(0-1 including loops), 
totalDuration
, 
timeScale
, 
paused
, 
persist
, 
data
(TweenData[]), 
isInfinite
, 
isNumberTween
.
MethodPurpose
play()
/ 
pause()
/ 
resume()
播放控制。
stop()
停止并标记为待移除。触发
onStop
。
restart()
重置并重播。
complete(delay?)
立即完成。
completeAfterLoop(loops?)
再播放N次循环后完成。
seek(ms, delta?, emit?)
跳转到指定毫秒偏移位置。
forward(ms)
/ 
rewind(ms)
向前/向后跳转指定毫秒。
setTimeScale(v)
/ 
getTimeScale()
设置/获取单个补间的播放速度。
setCallback(type, fn, params?)
创建后设置回调。
getValue(index?)
获取当前TweenData的值。
updateTo(key, value, startToCurrent?)
补间播放中修改结束值。
hasTarget(target)
/ 
isPlaying()
/ 
isPaused()
状态检查。
remove()
/ 
destroy()
清理资源。
关键属性: 
targets
、
duration
、
elapsed
、
progress
（0-1）、
totalProgress
（0-1，包含循环）、
totalDuration
、
timeScale
、
paused
、
persist
、
data
（TweenData[]）、
isInfinite
、
isNumberTween
。

TweenChain Instance

补间链实例

Extends 
BaseTween
. Has all tween playback methods (
play
, 
pause
, 
resume
, 
stop
, 
restart
, 
complete
, etc.) plus 
add(tweenConfigs)
to append tweens dynamically. Properties: 
currentTween
, 
currentIndex
.
继承自
BaseTween
。拥有所有补间播放方法（
play
、
pause
、
resume
、
stop
、
restart
、
complete
等），还支持
add(tweenConfigs)
动态追加补间。属性: 
currentTween
、
currentIndex
。

Gotchas

注意事项

  • Underscore properties are ignored. A tween will skip any property whose name starts with 
    _
    .
  • Tweens auto-destroy. If you store a reference to a tween and try to use it after completion, it may be destroyed. Set 
    persist: true
    to keep it alive, but you must 
    destroy()
    it yourself when done.
  • repeat
    vs 
    loop
    .     
    repeat
    is per-property (on TweenData). 
    loop
    restarts the entire tween. A 
    repeat
    of 1 means the property plays twice total.
  • loop: -1
    means 
    onComplete
    never fires.     An infinitely looping tween never completes. Use 
    completeAfterLoop()
    to end it gracefully.
  • Seeking suppresses events. When calling 
    tween.seek()
    , events and callbacks are not dispatched unless you pass 
    true
    as the third argument.
  • Stagger only works with multiple targets. Using 
    this.tweens.stagger()
    on a single-target tween has no visible stagger effect.
  • Destroyed targets. A tween completes early if its target has 
    isDestroyed
    set to 
    true
    . Always clean up tweens before destroying the objects they reference, or rely on this auto-check.
  • TweenManager.timeScale multiplies with Tween.timeScale. The effective speed is 
    managerTimeScale * tweenTimeScale
    . Setting either to 0 freezes the tween.
  • Duration cannot be zero. Internally clamped to a minimum of 0.01ms.
  • TweenChain 
    targets
    are inherited.     If you set 
    targets
    at the chain level, individual tweens in the chain inherit them unless they specify their own.
  • 下划线开头的属性会被忽略。 补间会跳过任何名称以下划线开头的属性。
  • 补间会自动销毁。 如果你存储了补间的引用，在补间完成后尝试使用它可能会失败，因为它已被销毁。设置
    persist: true
    可保持其存活，但使用完毕后必须手动调用
    destroy()
    。
  • repeat
    vs 
    loop
    。     
    repeat
    是属性级的（属于TweenData）。
    loop
    会重启整个补间。
    repeat
    为1意味着该属性总共播放两次。
  • loop: -1
    意味着
    onComplete
    永远不会触发。     无限循环的补间永远不会完成。使用
    completeAfterLoop()
    可优雅地结束它。
  • 跳转播放位置会抑制事件。 调用
    tween.seek()
    时，默认不会触发事件和回调，除非你将第三个参数设为
    true
    。
  • 交错动画仅对多目标有效。 对单目标补间使用
    this.tweens.stagger()
    不会产生可见的交错效果。
  • 已销毁的目标对象。 如果补间的目标对象的
    isDestroyed
    设为
    true
    ，补间会提前完成。销毁对象前请务必清理相关补间，或依赖这个自动检查机制。
  • TweenManager.timeScale与Tween.timeScale会相乘。 实际播放速度是
    managerTimeScale * tweenTimeScale
    。将其中任何一个设为0都会冻结补间。
  • 持续时间不能为0。 内部会将其钳制到最小0.01毫秒。
  • 补间链的
    targets
    会被继承。     如果在链级设置了
    targets
    ，链中的单个补间会继承该目标，除非它们自己指定了目标。

Source File Map

源文件映射

FilePurpose
src/tweens/TweenManager.js
Scene plugin. 
add
, 
chain
, 
stagger
, 
killAll
, etc.
src/tweens/tween/Tween.js
Individual tween. Targets, TweenData array, seeking, update.
src/tweens/tween/TweenChain.js
Sequential tween playback via ordered child Tweens.
src/tweens/tween/BaseTween.js
Shared base. EventEmitter, callbacks, state machine.
src/tweens/tween/BaseTweenData.js
Per-property state: duration, delay, yoyo, repeat, progress.
src/tweens/tween/TweenData.js
Numeric property tweening (extends BaseTweenData).
src/tweens/tween/TweenFrameData.js
Texture frame tweening (extends BaseTweenData).
src/tweens/builders/TweenBuilder.js
Parses config into Tween instance.
src/tweens/builders/TweenChainBuilder.js
Parses config into TweenChain instance.
src/tweens/builders/NumberTweenBuilder.js
Builds target-less number tweens.
src/tweens/builders/StaggerBuilder.js
Creates stagger functions.
src/tweens/events/
Event constants (
TWEEN_ACTIVE
, 
TWEEN_START
, etc.).
src/tweens/typedefs/
JSDoc typedefs for all config objects.
src/math/easing/EaseMap.js
Maps ease string names to functions.
FilePurpose
src/tweens/TweenManager.js
场景插件。包含
add
、
chain
、
stagger
、
killAll
等方法。
src/tweens/tween/Tween.js
单个补间。处理目标对象、TweenData数组、跳转播放位置、更新逻辑。
src/tweens/tween/TweenChain.js
通过有序的子补间实现顺序播放。
src/tweens/tween/BaseTween.js
共享基类。包含EventEmitter、回调、状态机。
src/tweens/tween/BaseTweenData.js
单属性状态：持续时间、延迟、往返、重复、进度。
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
将缓动字符串名称映射到对应函数。