主题
EUINodeBase
概览
| 字段 | 值 |
|---|---|
| Kind | Unit · 单位 Unit |
| Realm | common |
继承关系
- Unit（4 属性 / 25 函数 / 6 事件）
- [EUINodeBase]（34 属性 / 8 函数 / 4 事件）
- EUIButton（13 属性）
- EUIClippingNode（4 属性）
- EUIEffect（3 属性 / 2 函数）
- EUIGridLayout（10 属性 / 1 函数）
- EUIImage（4 属性）
- EUIInputField（16 属性 / 1 事件）
- EUILayout（1 属性）
- EUIListLayout（8 属性 / 1 函数）
- EUIListView（8 属性 / 2 函数）
- EUILoadingBar（4 属性）
- EUIProgressTimer（4 属性）
- EUIRichTextLabel（30 属性）
- EUIRootNode
- EUISceneNode（5 属性 / 1 函数）
- EUISimpleRichTextLabel（20 属性）
- EUITableLayout（6 属性 / 1 函数）
- EUITextLabel（14 属性）
- [EUINodeBase]（34 属性 / 8 函数 / 4 事件）
继承成员
1 个来源 / 4 属性 / 25 函数 / 6 事件
- 来自 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、GetFullPath、GetDebugId - 事件：
ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying
- 属性：
界面节点是搭建游戏界面层级的基础单位，负责管理节点的显示、坐标、锚点、尺寸、旋转、透明度等布局属性，同时支持触摸音效、触摸开关、触摸吞噬以及针对屏幕边缘的自适应规则。它还提供补间动画方法用于平滑改变位置、尺寸与透明度，并且能够通过触摸开始、移动、结束和点击等事件响应玩家操作，配合保留与释放机制维护节点引用。
适用场景
在客户端界面开发中，通常先获取本地玩家的界面根节点，再创建界面节点挂载到根节点下，配置其布局与触摸行为，并监听点击或触摸事件实现交互功能。例如制作可点击的按钮面板，或是需要位移动画提示的界面元素。
使用要点
先通过游戏服务获取本地玩家，再经由玩家界面管理器获取根节点，随后调用世界对象创建界面节点实例，并将父节点设置为该根节点。创建后可直接读写可见性、尺寸、坐标等属性，也可以连接节点的点击与触摸事件；需要动画时调用位置、尺寸或透明度补间方法，并传入缓动方向、缓动样式、时长等参数。
注意事项
EUI 节点通过 World:CreateUnit 创建时，必须把 Parent 设置为当前玩家 PlayerGui.EuiManager:GetRootNode()；不能自行直接构造（Unit 不可直接构造），也不要调用未进入 Meta 的 EUIManager 私有工厂。Meta 公开且可写的属性统一支持 node.Property = value，也支持隐式 SetProperty(value) 访问器；读取可使用 node.Property 或 GetProperty()。readOnly=true 的属性只允许读取/Get，不允许直接赋值或 Set。EUINodeBase 显式列出的 SetPosition/SetRotation 等方法是等价兼容入口，不表示禁止直接赋值。普通属性修改优先使用直接赋值，TweenPosition/TweenSize 等带动画语义的方法不属于等价属性写入。
代码示例
创建基础 EUI 节点并设置显示区域
lua
-- @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 node = World:CreateUnit("EUINodeBase", {
Parent = rootNode,
Position = Vector2.New(0, 0),
Size = Vector2.New(100, 40),
})
node.Visible = true
node.Opacity = 0.9属性 (34)
| Name | 类型 | 默认值 | 说明 |
|---|---|---|---|
Visible | Bool | true | 控制节点是否可见。 |
Position | Vector2 | [0, 0] | UI 节点相对于父节点的位置坐标。 |
Anchor | Vector2 | [0.5, 0.5] | UI 节点的锚点位置，决定节点相对于父节点的对齐基准点。 |
FlippedX | Bool | false | 控制节点是否沿水平方向翻转显示。 |
FlippedY | Bool | false | 控制节点是否沿垂直方向翻转显示。 |
Size | Vector2 | [0, 0] | 节点的显示尺寸。 |
Rotation | Float | 0.0 | 节点的旋转角度，以度为单位。 |
Opacity | Float | 1.0 | 节点的透明度，取值范围通常为 0 到 1。 |
TouchBeginAudio | String | "" | 按下音效，指定节点在被按下时播放的音效资源标识。 |
TouchEndAudio | String | "" | 抬起音效，指定节点在手指抬起时播放的音效资源标识。 |
TouchClickAudio | String | "" | 点击音效，指定节点在完成点击时播放的音效资源标识。 |
TouchbeginEvent | String | "" | 触摸开始时触发的事件名称。 |
ClickEvent | String | "" | 节点被点击时触发的事件名称。 |
TouchendEvent | String | "" | 触摸结束时触发的事件名称。 |
LongtouchEvent | String | "" | 节点被长按时触发的事件名称。 |
ShowEvent | String | "" | 节点被显示时触发的事件名称。 |
HideEvent | String | "" | 节点被隐藏时触发的事件名称。 |
TouchEnabled | Bool | false | 控制节点是否可接收触摸事件。 |
SwallowTouchEnabled | Bool | true | 控制节点是否吞噬触摸事件，即是否阻止触摸事件向父节点传递。 |
TopAdaptMode | Int | 0 (None) | 顶部边缘的自适应模式。 |
TopAdaption | Float | 0.0 | 顶部边缘的自适应偏移量。 |
BottomAdaptMode | Int | 0 (None) | 底部边缘的自适应模式。 |
BottomAdaption | Float | 0.0 | 底部边缘的自适应偏移量。 |
LeftAdaptMode | Int | 0 (None) | 左边边缘的自适应模式。 |
LeftAdaption | Float | 0.0 | 左边边缘的自适应偏移量。 |
RightAdaptMode | Int | 0 (None) | 右边边缘的自适应模式。 |
RightAdaption | Float | 0.0 | 右边边缘的自适应偏移量。 |
AnchorXAdaptMode | Int | 0 (None) | 锚点 X 方向的自适应模式。 |
AnchorXAdaption | Float | - | 锚点 X 方向的自适应偏移量。 |
AnchorYAdaptMode | Int | 0 (None) | 锚点 Y 方向的自适应模式。 |
AnchorYAdaption | Float | - | 锚点 Y 方向的自适应偏移量。 |
LocalZOrder | Int | 0 | 节点在父节点中的局部渲染层级。 |
LayoutOrder | Int | 0 | 节点在布局中的排序序号。 |
Scale | Vector2 | [1.0, 1.0] | UI 节点的缩放比例。 |
关联类型
事件 (4)
OnTouchBegan
签名：OnTouchBegan(euiTouchInfo: EUITouchInfo, player: Player) 触发：local
当玩家的触摸在 EUINodeBase 节点上按下（触摸开始）时触发。
| 回调参数 | 类型 | 说明 |
|---|---|---|
euiTouchInfo | EUITouchInfo | 交互参数 |
player | Player | 玩家 |
示例代码
监听 EUINodeBase.OnTouchBegan 事件的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
euiNodeBase.OnTouchBegan:Once(function(euiTouchInfo, player)
print("euiTouchInfo: " .. tostring(euiTouchInfo))
end)OnTouchMoved
签名：OnTouchMoved(euiTouchInfo: EUITouchInfo, player: Player) 触发：local
当玩家的触摸在 EUINodeBase 节点上移动（按住并滑动）时触发。
| 回调参数 | 类型 | 说明 |
|---|---|---|
euiTouchInfo | EUITouchInfo | 交互参数 |
player | Player | 玩家 |
示例代码
监听 EUINodeBase.OnTouchMoved 事件的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
euiNodeBase.OnTouchMoved:Once(function(euiTouchInfo, player)
print("euiTouchInfo: " .. tostring(euiTouchInfo))
end)OnTouchEnded
签名：OnTouchEnded(euiTouchInfo: EUITouchInfo, player: Player) 触发：local
当玩家的触摸在 EUINodeBase 节点上结束（抬起）时触发。
| 回调参数 | 类型 | 说明 |
|---|---|---|
euiTouchInfo | EUITouchInfo | 交互参数 |
player | Player | 玩家 |
示例代码
监听 EUINodeBase.OnTouchEnded 事件的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
euiNodeBase.OnTouchEnded:Once(function(euiTouchInfo, player)
print("euiTouchInfo: " .. tostring(euiTouchInfo))
end)OnClicked
签名：OnClicked(player: Player) 触发：local
当玩家的触摸在 EUINodeBase 节点上完成一次点击（按下并抬起）时触发。
| 回调参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家 |
示例代码
监听 EUINodeBase.OnClicked 事件的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
euiNodeBase.OnClicked:Once(function(player)
print("player: " .. tostring(player))
end)函数 (8)
RemoveFromParent
签名：RemoveFromParent() -> void
将节点从其父节点中移除。
返回值 void
示例代码
把 EUI 节点从父节点移除
lua
-- @runtime client
local function removeNode(node)
if node == nil then return end
node:RemoveFromParent()
endGetFullPath
签名：GetFullPath() -> String (UI 路径字符串（'.' 分隔）)
获取 UI 节点在 UI 树中的完整路径，以 '.' 分隔。
返回值 String (UI 路径字符串（'.' 分隔）)
示例代码
调用 EUINodeBase:GetFullPath 的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
local result = euiNodeBase:GetFullPath() -- 返回 String
if result ~= nil then
print(result)
if result ~= "" then
print("返回了非空字符串")
end
endTweenPosition
签名：TweenPosition(endPosition: Vector2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: Float, override: Bool, callback: Function) -> Bool (是否成功启动新 Tween)
对 UI 节点的位置进行缓动动画。
| 参数 | 类型 | 说明 |
|---|---|---|
endPosition | Vector2 | 目标位置(绝对像素) |
easingDirection | EasingDirection | 缓动方向(默认 Out) |
easingStyle | EasingStyle | 缓动样式(默认 Quad) |
time | Float | 时长(秒,默认 1) |
override | Bool | 是否抢占同通道旧 Tween(默认 false) |
callback | Function | 完成或被抢占时触发的回调(status:TweenStatus) |
返回值 Bool (是否成功启动新 Tween)
示例代码
把节点补间到目标位置
lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local player = Players.LocalPlayer
if player == nil then return end
local node = World:CreateUnit("EUINodeBase", {
Parent = player.PlayerGui.EuiManager:GetRootNode(),
Position = Vector2.New(40, 40),
Size = Vector2.New(100, 40),
})
node:TweenPosition(Vector2.New(160, 100), Enums.EasingDirection.Out, Enums.EasingStyle.Quad, 0.3, true, function()
print("位置补间完成")
end)TweenSize
签名：TweenSize(endSize: Vector2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: Float, override: Bool, callback: Function) -> Bool (是否成功启动新 Tween)
对 UI 节点的尺寸进行缓动动画。
| 参数 | 类型 | 说明 |
|---|---|---|
endSize | Vector2 | 目标尺寸(绝对像素) |
easingDirection | EasingDirection | 缓动方向(默认 Out) |
easingStyle | EasingStyle | 缓动样式(默认 Quad) |
time | Float | 时长(秒,默认 1) |
override | Bool | 是否抢占同通道旧 Tween(默认 false) |
callback | Function | 完成或被抢占时触发的回调(status:TweenStatus) |
返回值 Bool (是否成功启动新 Tween)
示例代码
把节点尺寸补间到目标大小
lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local player = Players.LocalPlayer
if player == nil then return end
local node = World:CreateUnit("EUINodeBase", {
Parent = player.PlayerGui.EuiManager:GetRootNode(),
Size = Vector2.New(100, 40),
})
node:TweenSize(Vector2.New(240, 80), Enums.EasingDirection.Out, Enums.EasingStyle.Quad, 0.3, true, function()
print("尺寸补间完成")
end)TweenSizeAndPosition
签名：TweenSizeAndPosition(endSize: Vector2, endPosition: Vector2, easingDirection: EasingDirection, easingStyle: EasingStyle, time: Float, override: Bool, callback: Function) -> Bool (是否成功启动新 Tween)
同时对 UI 节点的尺寸和位置进行缓动动画。
| 参数 | 类型 | 说明 |
|---|---|---|
endSize | Vector2 | 目标尺寸(绝对像素) |
endPosition | Vector2 | 目标位置(绝对像素) |
easingDirection | EasingDirection | 缓动方向(默认 Out) |
easingStyle | EasingStyle | 缓动样式(默认 Quad) |
time | Float | 时长(秒,默认 1) |
override | Bool | 是否抢占 Pos/Size 两通道旧 Tween(默认 false) |
callback | Function | 完成或被抢占时触发的回调(status:TweenStatus) |
返回值 Bool (是否成功启动新 Tween)
示例代码
同时补间节点尺寸和位置
lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local player = Players.LocalPlayer
if player == nil then return end
local node = World:CreateUnit("EUINodeBase", {
Parent = player.PlayerGui.EuiManager:GetRootNode(),
Position = Vector2.New(40, 40),
Size = Vector2.New(100, 40),
})
node:TweenSizeAndPosition(Vector2.New(240, 80), Vector2.New(160, 100), Enums.EasingDirection.Out, Enums.EasingStyle.Quad, 0.3, true, function()
print("尺寸和位置补间完成")
end)TweenOpacity
签名：TweenOpacity(endOpacity: Float, easingDirection: EasingDirection, easingStyle: EasingStyle, time: Float, override: Bool, callback: Function) -> Bool (是否成功启动新 Tween)
对 UI 节点的透明度进行缓动动画。
| 参数 | 类型 | 说明 |
|---|---|---|
endOpacity | Float | 目标透明度(0~1) |
easingDirection | EasingDirection | 缓动方向(默认 Out) |
easingStyle | EasingStyle | 缓动样式(默认 Quad) |
time | Float | 时长(秒,默认 1) |
override | Bool | 是否抢占 Opacity 通道旧 Tween(默认 false) |
callback | Function | 完成或被抢占时触发的回调(status:TweenStatus) |
返回值 Bool (是否成功启动新 Tween)
示例代码
调用 EUINodeBase:TweenOpacity 的示例。
lua
-- @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 euiNodeBase = World:CreateUnit("EUINodeBase", { Parent = rootNode })
local endOpacity = 0.0 -- Float
local easingDirection = Enums.EasingDirection.In -- EasingDirection
local easingStyle = Enums.EasingStyle.Linear -- EasingStyle
local time = 1.0 -- Float
local override = false -- Bool
local callback = function() end -- Function
local result = euiNodeBase:TweenOpacity(endOpacity, easingDirection, easingStyle, time, override, callback) -- 返回 Bool
if result then
print("调用结果为 true")
else
print("调用结果为 false")
endRetain
签名：Retain() -> void
增加节点的引用计数，防止被意外释放。
返回值 void
示例代码
在异步使用期间保留节点并成对释放
lua
-- @runtime client
local function useNodeLater(node)
if node == nil then return end
node:Retain()
game:GetService("Task"):Delay(1, function()
print("异步读取节点路径:", node:GetFullPath())
node:Release()
end)
endRelease
签名：Release() -> void
释放节点占用的资源。
⚙ Release 必须与此前成功执行的 Retain 成对调用；不要在未 Retain 的节点上单独调用。
返回值 void
示例代码
释放此前保留的节点引用
lua
-- @runtime client
local function finishUsingNode(node)
if node == nil then return end
-- 仅在调用方此前已对同一节点执行 Retain 时释放
node:Release()
end