工坊手册

主题

TweenService ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

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

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

补间动画服务，用于为场景中的 Unit 实例创建属性过渡动画，让位置、尺寸、透明度等可数值化的属性随时间平滑变化。调用 Create 时需要提供目标实例、TweenInfo 补间参数与目标属性表，返回值是一个 Tween 对象，后续的播放、暂停与取消都由该对象负责。它把缓动风格的配置与实例绑定的创建过程集中到同一入口，便于统一管理动画的生成。

适用场景 ​

常见于界面节点淡入淡出、面板滑入滑出、提示文字渐显或模型位置平滑移动等需要缓动效果的场合。开发者先取得服务实例，针对某个 Unit 生成补间，播放完成后借助结束事件继续推进后续逻辑。

使用要点 ​

先用 game:GetService("TweenService") 取得服务实例，再用 TweenInfo.New(...) 组织时长、缓动风格、缓动方向、重复次数等参数，然后调用 tweenService:Create(unit, tweenInfo, goalTable) 生成 Tween 对象。目标表里的字段名需要与目标 Unit 的公开属性名对应，拿到 Tween 后可调用其 Play 开始播放，中途需要停止时调用 Pause 或 Cancel，并通过 Tween 的 Completed 事件获知播放结束。

注意事项 ​

Create 需要有效的 Unit 实例、TweenInfo 和与目标 Unit 公开属性匹配的目标表。通过返回 Tween 的 Completed 事件监听结束状态；若要从新的起始状态再次执行补间，请基于当时的目标状态重新创建 Tween。

代码示例 ​

创建 Tween 动画并播放（使用正确的 Unit 类型） ​

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

-- 创建 RenderUnit（作为补间目标）
local part = World:CreateUnit("RenderUnit", {
    RenderMeshId = "official://mesh/59268",
    ModelVisible = true,
    ModelAlpha = 1.0,
})
if part == nil then
    print('RenderUnit 创建失败，无法创建 Tween')
    return
end

-- 定义 TweenInfo 和目标值
local tweenInfo = TweenInfo.New(0.5, Enums.EasingStyle.Quad, Enums.EasingDirection.InOut)
local goal = { Position = Vector3.New(5, 0, 0) }

-- 创建并播放 Tween
local tween = TweenService:Create(part, tweenInfo, goal)
tween:Play()

-- 监听完成事件
tween.Completed:Once(function(playState)
    print('Tween 完成，状态:', playState)
    part:Destroy()
end)

关联类型 ​

函数 (1) ​

Create ​

签名：Create(instance: Unit, tweenInfo: TweenInfo, goalTable: Table) -> Tween (Tween 对象)

在 TweenService 上创建并返回一个 Tween 对象，用于让指定 Unit 实例的属性从当前值平滑过渡到目标表中给出的值；过渡的时长、缓动方式、循环与延迟等节奏由传入的 TweenInfo 描述。该函数只负责构建补间对象，返回的 Tween 不会自动开始播放。

参数类型说明
instanceUnit目标对象
tweenInfoTweenInfoTweenInfo 配置
goalTableTable目标属性表

返回值 Tween (Tween 对象)

示例代码

创建并播放位移 Tween

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

local target = World:CreateUnit("RenderUnit", {
    RenderMeshId = "official://mesh/59268",
    ModelVisible = true,
    ModelAlpha = 1.0,
})
if target == nil then
    print('RenderUnit 创建失败，无法创建 Tween')
    return
end

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(playState)
    print('Tween 完成状态:', playState)
    target:Destroy()
end)
tween:Play()