工坊手册

主题

Tween ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [Tween]（2 属性 / 3 函数 / 1 事件）

继承成员 ​

1 个来源 / 4 属性 / 25 函数 / 6 事件

Tween 是补间动画的播放控制对象，用于驱动目标对象的属性在一段时间内平滑过渡到目标值。它对外暴露 PlaybackState 表示当前播放阶段、Instance 指向被动画的目标对象，并提供 Play、Pause、Cancel 三个控制函数；当播放自然结束时触发 Completed 事件并携带结束状态。

适用场景 ​

当需要让某个对象的属性平滑变化而非瞬间跳变时，通常先由补间服务生成 Tween，再调用 Play() 启动过渡，例如界面面板的位移、缩放或透明度渐变。演示代码中即通过补间服务的 Create() 取得 Tween 后依次执行播放、暂停与取消操作。

使用要点 ​

先通过 game:GetService("TweenService") 取得补间服务，调用其 Create() 并传入目标对象与过渡参数，返回的 Tween 实例就是操作入口。拿到实例后调用 Play() 开始播放，需要临时停顿时调用 Pause()，确定不再继续时调用 Cancel() 终止。若要在动画自然结束时接续逻辑，应连接 Completed 事件并从回调参数中读取结束状态，同时可随时读取 PlaybackState 与 Instance 了解当前阶段与目标对象。

注意事项 ​

Tween 实例只能由 TweenService:Create() 返回，不可直接构造。Play() 开始播放，Pause() 暂停，Cancel() 取消播放并停止继续更新；不要把 Cancel() 描述为自然完成。需要获知自然结束时，监听 Completed 事件并读取回调中的 playbackState。

代码示例 ​

创建 Tween 并监听完成状态 ​

lua
-- @runtime client
local TweenService = game:GetService("TweenService")
local World = game:GetService("World")

local target = World:CreateUnit("RenderUnit", {
    Name = "FadeTarget",
    RenderMeshId = "official://mesh/59268",
    ModelAlpha = 1,
})

local tweenInfo = TweenInfo.New(0.5, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local tween = TweenService:Create(target, tweenInfo, {
    Position = Vector3.New(5, 0, 0),
})

tween.Completed:Once(function(playbackState)
    print("Tween 完成状态:", playbackState)
end)
tween:Play()

属性 (2) ​

Name类型默认值说明
PlaybackStateTweenPlayStateEnums.TweenPlayState.BeginTween 的 PlaybackState 属性表示该补间动画当前的播放状态，类型为 TweenPlayState 枚举，枚举项包括 Begin、Delayed、Playing、Paused、Completed、Cancelled。该属性为只读属性。
InstanceUnit-Tween 的 Instance 属性表示该补间动画（Tween）所作用的目标 Unit 对象，即通过 TweenService:Create 创建该 Tween 时传入的目标对象。该属性为只读属性，类型为 Unit。

关联类型 ​

事件 (1) ​

Completed ​

签名：Completed(playbackState: TweenStatus) 触发：local

Tween 结束时触发的事件，回调参数 playbackState 表示结束状态。

⚙ 当前公开 Meta 只声明 Completed 事件和 Cancel 方法，未明确 Cancel() 是否一定触发 Completed；处理回调时可根据 playbackState 区分状态，但不要把 Cancel() 当作自然完成。

回调参数类型说明
playbackStateTweenStatus完成状态

示例代码

监听 Tween 完成状态

lua
-- @runtime client
local TweenService = game:GetService("TweenService")
local World = game:GetService("World")
local target = World:CreateUnit("RenderUnit", { ModelAlpha = 1 })
local tweenInfo = TweenInfo.New(0.5, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local goal = { Position = Vector3.New(5, 0, 0) }
local tween = TweenService:Create(target, tweenInfo, goal)
tween.Completed:Once(function(playbackState)
    print("Tween 完成状态:", playbackState)
end)
tween:Play()

函数 (3) ​

Play ​

签名：Play() -> void

开始播放 Tween 动画，或从暂停状态恢复播放。

返回值 void

示例代码

播放 Tween

lua
-- @runtime client
local TweenService = game:GetService("TweenService")
local World = game:GetService("World")
local target = World:CreateUnit("RenderUnit", { ModelAlpha = 1 })
local tweenInfo = TweenInfo.New(0.5, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local goal = { Position = Vector3.New(5, 0, 0) }
local tween = TweenService:Create(target, tweenInfo, goal)
tween:Play()

Pause ​

签名：Pause() -> void

暂停当前正在播放的 Tween 动画，保留当前进度。

返回值 void

示例代码

暂停 Tween

lua
-- @runtime client
local TweenService = game:GetService("TweenService")
local World = game:GetService("World")
local target = World:CreateUnit("RenderUnit", { ModelAlpha = 1 })
local tweenInfo = TweenInfo.New(1.0, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local goal = { Position = Vector3.New(5, 0, 0) }
local tween = TweenService:Create(target, tweenInfo, goal)
tween:Play()
tween:Pause()

Cancel ​

签名：Cancel() -> void

取消正在播放的 Tween，使其停止继续更新；不要将取消播放等同于自然完成。

返回值 void

示例代码

取消 Tween

lua
-- @runtime client
local TweenService = game:GetService("TweenService")
local World = game:GetService("World")
local target = World:CreateUnit("RenderUnit", { ModelAlpha = 1 })
local tweenInfo = TweenInfo.New(1.0, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local goal = { Position = Vector3.New(5, 0, 0) }
local tween = TweenService:Create(target, tweenInfo, goal)
tween:Play()
tween:Cancel()