EUISlider

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • EUINodeBase（35 属性 / 12 函数 / 4 事件）
    • [EUISlider]（18 属性 / 4 事件）

继承成员

2 个来源 / 39 属性 / 36 函数 / 10 事件

• 来自 EUINodeBase（35 属性 / 12 函数 / 4 事件）
  • 属性：Visible、Position、Anchor、FlippedX、FlippedY、Size、Rotation、Opacity、TouchBeginAudio、TouchEndAudio、TouchClickAudio、TouchbeginEvent、ClickEvent、TouchendEvent、LongtouchEvent、ShowEvent、HideEvent、TouchEnabled、TouchDragEnabled、SwallowTouchEnabled、TopAdaptMode、TopAdaption、BottomAdaptMode、BottomAdaption、LeftAdaptMode、LeftAdaption、RightAdaptMode、RightAdaption、AnchorXAdaptMode、AnchorXAdaption、AnchorYAdaptMode、AnchorYAdaption、LocalZOrder、LayoutOrder、Scale
  • 函数：RemoveFromParent、GetFullPath、TweenPosition、TweenSize、TweenSizeAndPosition、TweenOpacity、Retain、Release、GetWorldPosition、ConvertToWorldPosition、ConvertToLocalPosition、HitTest
  • 事件：OnTouchBegan、OnTouchMoved、OnTouchEnded、OnClicked
• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

EUISlider 是界面中的可拖动滑动条控件，用于在指定区间内连续取值或按步长分段取值。它用 Progress 表示当前值，可通过 Direction 设定滑动方向，并用 MinValue、MaxValue、Step 约束取值范围与吸附步长，同时为轨道、填充条和滑块分别提供常态、按下、禁用等多套贴图与九宫拉伸区域。控件会派发 OnValueChanged、OnSlide、OnPressed、OnReleased 等本机事件，便于在拖动全过程中实时响应数值变化。

适用场景

常用于设置面板里的音量调节、画质档位选择或进度设定等需要连续取值的交互项，拖动滑块即可把结果回写到界面逻辑中。

使用要点

先通过 Players 服务的 LocalPlayer 进入 PlayerGui，在其 EuiManager 上调用 GetRootNode 拿到界面根节点，再以 game:GetService("World"):CreateUnit("EUISlider", {...}) 传入 Parent、Position、Size 创建实例，并从该调用的返回值持有对象。创建后设置 TrackImage、ProgressImage、HandleNormalImage 等贴图与 MinValue、MaxValue、Step，可按需填写 SlideEvent、PressEvent、ReleaseEvent 事件名。最后连接 OnValueChanged 或 OnSlide，在回调中读取 Progress 得到最新取值。

注意事项

该类型属于界面单位，只能通过 World 服务的 CreateUnit 创建并挂到 EUI 根节点下，不能像普通数据类型那样直接构造。四个事件均在本机触发，需要让其他端感知数值变化时应另行使用网络事件传递。把 Disabled 置为真时建议同步配置禁用态的填充条与滑块贴图，否则交互状态与外观会不一致。

代码示例

创建 EUISlider 实例

-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService('World')
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local eUISlider = World:CreateUnit("EUISlider", { Parent = rootNode })
if eUISlider == nil then return end
print('EUISlider 已创建:', eUISlider.Name)

属性 (18)

Name	类型	默认值	说明
Progress	Float	0	当前范围内的实际数值。关闭自定义范围时取值范围为 0～1，开启后使用 MinValue 与 MaxValue。赋值会被裁剪到有效范围并按步长吸附，仅在数值真正改变时通知。
Direction	EUIScrollDirection	Enums.EUIScrollDirection.Horizontal	滑动方向，决定滑动条数值随触摸位置变化的方向。类型为 EUIScrollDirection 枚举：横向时从左到右递增，竖向时从上到下递增。
Disabled	Bool	false	布尔型禁用开关。为 true 时禁用滑动条交互并显示禁用状态；若此时正在进行拖动，则以取消状态结束本次触摸。
SlideEvent	String	""	数值变化事件名。实际数值变化时按该名称派发自定义事件，参数为当前范围内的实际数值 progress；空字符串表示不派发该自定义事件。
PressEvent	String	""	按下事件名。有效触摸开始时按该名称派发自定义事件，参数为应用本次点击位置前的实际数值 progress；空字符串表示不派发该自定义事件。
ReleaseEvent	String	""	抬手事件名。有效触摸结束时按该名称派发自定义事件，参数为最终实际数值 progress 与是否取消 canceled；空字符串表示不派发该自定义事件。
TrackImage	String	official://image/30024	滑动条轨道的背景图片，取值为图片资源协议地址。
ProgressImage	String	official://image/30025	用于按当前位置比例显示填充进度的填充条图片，取值为图片资源协议地址。
ProgressDisabledImage	String	official://image/30044	禁用状态下用于显示当前位置比例的禁用填充条图片，取值为图片资源协议地址。
HandleNormalImage	String	official://image/30026	滑块在未按下且未禁用状态下使用的图片，取值为图片资源协议地址。
HandlePressedImage	String	official://image/30027	滑块处于按下状态时使用的图片，取值为图片资源协议地址。
HandleDisabledImage	String	official://image/30028	滑块处于禁用状态时使用的图片，取值为图片资源协议地址。
RangeEnabled	Bool	false	自定义范围开关。开启后使用 MinValue 与 MaxValue 作为有效范围，关闭时使用 0～1。切换时会保持原位置比例，再按当前步长吸附。
MinValue	Float	0	自定义范围的最小值，必须为有限数值且小于 MaxValue；即使未启用自定义范围，该配置仍需保持合法。修改范围时会保持原位置比例，再按步长吸附。
MaxValue	Float	1	自定义范围的最大值，必须为有限数值且大于 MinValue；即使未启用自定义范围，该配置仍需保持合法。修改范围时会保持原位置比例，再按步长吸附。
Step	Float	0	吸附步长，取值为非负有限数值，0 表示连续滑动。吸附以当前有效最小值为起点就近取整，中点取较大值，最大端点始终可达；修改步长后会对当前实际数值重新吸附。
TrackStretchArea	Vector4	[0, 0, 0, 0]	轨道九宫，类型为 Vector4，用于配置轨道背景图片的九宫格拉伸区域。
ProgressStretchArea	Vector4	[0, 0, 0, 0]	填充九宫，类型为 Vector4，用于配置填充条的九宫格拉伸区域。

关联类型

• EUINodeBase
• EUIScrollDirection
• Vector4

事件 (4)

OnValueChanged

签名：OnValueChanged(progress: Float) 触发：local

数值变化事件，在滑动条实际数值变化时触发，回调参数 progress 为当前范围内的实际数值。

回调参数	类型	说明
progress	Float	裁剪和吸附后的实际数值，不是固定的0～1位置比例。

示例代码

监听 EUISlider.OnValueChanged 事件的示例。

-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local euiSlider = World:CreateUnit("EUISlider", { Parent = rootNode })
euiSlider.OnValueChanged:Once(function(progress)
    print("progress: " .. tostring(progress))
end)

OnSlide

签名：OnSlide(progress: Float) 触发：local

数值变化事件（兼容入口），在滑动条实际数值变化时触发，回调参数 progress 为当前范围内的实际数值。

回调参数	类型	说明
progress	Float	裁剪和吸附后的实际数值，不是固定的0～1位置比例。

示例代码

监听 EUISlider.OnSlide 事件的示例。

-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local euiSlider = World:CreateUnit("EUISlider", { Parent = rootNode })
euiSlider.OnSlide:Once(function(progress)
    print("progress: " .. tostring(progress))
end)

OnPressed

签名：OnPressed(progress: Float) 触发：local

按下事件，在玩家开始有效触摸滑动条时触发，回调参数 progress 为触发时的实际数值。

回调参数	类型	说明
progress	Float	应用本次点击位置前的实际数值。

示例代码

监听 EUISlider.OnPressed 事件的示例。

-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local euiSlider = World:CreateUnit("EUISlider", { Parent = rootNode })
euiSlider.OnPressed:Once(function(progress)
    print("progress: " .. tostring(progress))
end)

OnReleased

签名：OnReleased(progress: Float, canceled: Bool) 触发：local

抬手事件，在有效触摸结束时触发，回调参数为最终实际数值 progress 与是否取消 canceled。

回调参数	类型	说明
progress	Float	当前范围内的实际数值；抬手事件中为本次触摸的最终值。
canceled	Bool	正常抬手为false；触摸取消或交互失效导致结束时为true。

示例代码

监听 EUISlider.OnReleased 事件的示例。

-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local euiSlider = World:CreateUnit("EUISlider", { Parent = rootNode })
euiSlider.OnReleased:Once(function(progress, canceled)
    print("progress: " .. tostring(progress))
end)