跳至正文
版本：最新版 - a1.169.2 ⚖️

🪟 Widget

控件类支持通过脚本生成虚幻引擎的 Widget 类，并能像蓝图一样对它们进行操作！

Client Only🧑‍💻API Source
👪Inheritance
This class shares methods and events from Base Entity.

Widget 类提供了一种非常灵活的方式，可以在游戏内创建和使用虚幻控件作为 UI。

备注

Widget 类中未公开大部分参数，应使用 CallBlueprintEvent() 方法进行调用，该方法会调用底层特定的 Widget 方法。

🎒 示例​

创建一个简单的原生文本并将其添加到屏幕​

Client/Index.lua
local my_text = Widget(NativeWidget.Text)
my_text:CallBlueprintEvent("SetText", "Hello World!")
my_text:AddToViewport()
提示

SetText 是来自 UTextBlock 的方法，它是与 NativeWidget.Text 关联的 Widget。

创建带有子项的控件​

Client/Index.lua
local my_vertical_box = Widget(NativeWidget.VerticalBox)
my_vertical_box:AddToViewport()

local my_text = Widget(NativeWidget.Text)
my_text:CallBlueprintEvent("SetText", "Hello World!")

local my_button = Widget(NativeWidget.Button)

my_vertical_box:AddChild(my_text)
my_vertical_box:AddChild(my_button)

将 WebUI 用作图像笔刷​

Client/Index.lua
local webui = WebUI("mywebui", "https://google.com", WidgetVisibility.Hidden)

local my_image = Widget(NativeWidget.Image)
my_image:CallBlueprintEvent("SetBrushFromMaterial", webui)
my_image:AddToViewport()
提示

SetBrushFromMaterial 是来自 UImage 的方法，并且接收一个 MaterialInstance 作为参数。传入 WebUI、SceneCapture 或 Canvas 作为参数时，会自动将其转换为其内部材质！

订阅调度器​

Client/Index.lua
local my_button = Widget(NativeWidget.Button)

-- 在内部添加文本
local my_text = Widget(NativeWidget.Text)
my_text:CallBlueprintEvent("SetText", "Press Me!")
my_button:AddChild(my_text)

-- 绑定原生 OnClicked 调度器
my_button:BindBlueprintEventDispatcher("OnClicked", function()
	Console.Log("clicked!")
end)

-- 将按钮添加到视口（将填满整个屏幕）
my_button:AddToViewport()

📚 库和框架​

以下是社区创建的使用 Widget 扩展其可能性的库和框架列表：

WGUI

由 NegativeName 制作的用于构建用户界面的框架

🛠 构造函数​

UserWidget Constructor​

传入一个 UserWidget 蓝图来生成一个控件

local my_widget = Widget(blueprint_path)

Parameters

TypeNameDefaultDescription
Blueprint Referenceblueprint_path Required parameter 要生成的自定义 UserWidget 蓝图路径

Native Widget Constructor​

传入一个 NativeWidget 枚举来生成一个控件

local my_widget = Widget(native_widget)

Parameters

TypeNameDefaultDescription
NativeWidgetnative_widget Required parameter 要生成的原生控件之一

🦠 函数​

Inherited Entity Functions
Widget inherits from Base Entity Class, sharing it's methods and functions:
Base Entityscripting-reference/classes/base-classes/entity
ReturnsNameDescription
BroadcastRemoteEvent直接在此实体上向所有玩家调用自定义远程事件
BroadcastRemoteInRadiusEvent直接针对此实体调用自定义远程事件，并将该事件传递给半径范围内的所有玩家
CallRemoteEvent直接在此实体上向特定玩家调用自定义远程事件
CallRemoteEvent直接在此实体上调用自定义远程事件
CallRemotePlayersEvent直接在此实体上调用自定义远程事件，并将事件传递给玩家列表
Destroy销毁该实体
FinishSpawn如果此实体是以延迟 spawn_mode 生成的，则完成生成过程并将该实体发送至客户端
table of stringGetAllValuesKeys获取所有存储值的键名列表
tableGetClass获取该实体的类
integerGetID获取该实体的全网通用网络 ID（在客户端和服务器上相同）
anyGetValue获取此实体上存储在给定键处的 值
booleanHasAuthority获取本地上下文是否对此实体拥有主控（如果由客户端生成则为 true，由服务器生成则为 false）
booleanIsA递归检查此实体是否继承自某个类
booleanIsBeingDestroyed如果该实体正在被销毁，则返回 true
booleanIsSpawned获取此实体是否已完成生成
booleanIsValid如果该实体有效（即未被销毁且指向一个有效的实体），则返回 true
SetSpawnMode从继承类的构造函数中覆盖此实体完成生成的时间点
SetValue在此实体中设置一个值
functionSubscribe在这个特定实体上订阅一个事件
functionSubscribeRemote在这个特定实体上订阅一个从服务器调用的自定义远程事件
Unsubscribe退订此包内该实体中此 事件 的所有回调，或者仅取消传入的特定回调
ReturnsNameDescription
AddChild如果此控件为 Panel，则向该控件容器中添加一个新的子控件
AddToViewport将其添加到游戏视口中，填满整个屏幕
functionBindBlueprintEventDispatcher分配并绑定一个蓝图事件分发器
BringToFront将此控件置于所有 WebUI 和控件的最前面
varargs of anyCallBlueprintEvent调用一个蓝图事件或函数
anyGetBlueprintPropertyValue获取蓝图属性/变量的值
WidgetVisibilityGetVisibility返回当前 WebUI 的可见性
SetBlueprintPropertyValue直接设置蓝图属性/变量的值
SetContentForSlot如果此控件为 UserWidget，则按名称为指定槽位设置控件内容
SetFocus启用此控件的焦点
SetSlotAlignment设置水平和垂直定位的插槽对齐方式
SetSlotCanvasLayout将布局设为屏幕上的画布
SetSlotPadding设置水平和垂直间距的插槽内边距
SetSlotSize设置插槽大小和尺寸规则
SetVisibility设置其在屏幕上的可见性
Widget3DSpawnWidget3D生成一个在世界中渲染此控件的 3D 控件 Actor
UnbindBlueprintEventDispatcher解绑一个蓝图事件分发器
Moderate

AddChild​

如果此控件为 Panel，则向该控件容器中添加一个新的子控件
my_widget:AddChild(other)

Parameters

TypeParameterDefaultDescription
WebUI or Widgetother Required parameter 要添加的 WebUI 或 Widget
Moderate

AddToViewport​

将其添加到游戏视口中，填满整个屏幕
my_widget:AddToViewport()
Slow

BindBlueprintEventDispatcher​

分配并绑定一个蓝图事件分发器
local ret = my_widget:BindBlueprintEventDispatcher(dispatcher_name, callback)

Parameters

TypeParameterDefaultDescription
stringdispatcher_name Required parameter 事件分发器名称
functioncallback Required parameter 要调用的回调函数 with this format

Returns

TypeDescription
function回调函数本身
Optimal

BringToFront​

将此控件置于所有 WebUI 和控件的最前面。

注：只有在控件的父级是视口时才能调用此方法！
my_widget:BringToFront()
Slow

CallBlueprintEvent​

调用一个蓝图事件或函数

在客户端返回所有函数返回值
local ret_01, ret_02, ... = my_widget:CallBlueprintEvent(event_name, arguments...?)

Parameters

TypeParameterDefaultDescription
stringevent_name Required parameter 事件或函数名称
anyarguments...?nil
要传递给该事件的参数序列

Returns

TypeDescription
varargs of any函数的返回值
Slow

GetBlueprintPropertyValue​

获取蓝图属性/变量的值
local ret = my_widget:GetBlueprintPropertyValue(property_name)

Parameters

TypeParameterDefaultDescription
stringproperty_name Required parameter 蓝图变量的名称

Returns

TypeDescription
any值

See also SetBlueprintPropertyValue.

Optimal

GetVisibility​

返回当前 WebUI 的可见性
local visibility = my_widget:GetVisibility()

Returns

TypeDescription
WidgetVisibility当前 WebUI 的可见性

See also SetVisibility.

Slow

SetBlueprintPropertyValue​

直接设置蓝图属性/变量的值
my_widget:SetBlueprintPropertyValue(property_name, value)

Parameters

TypeParameterDefaultDescription
stringproperty_name Required parameter 蓝图变量的名称
anyvalue Required parameter 要设置的值

See also GetBlueprintPropertyValue.

Moderate

SetContentForSlot​

如果此控件为 UserWidget，则按名称为指定槽位设置控件内容
my_widget:SetContentForSlot(slot_name, widget?)

Parameters

TypeParameterDefaultDescription
stringslot_name Required parameter 命名槽位的名称
Widgetwidget?nil
传入 nil 以将其移除
Optimal

SetFocus​

启用此控件的焦点。

启用此控件的焦点（即可以接收键盘输入并触发输入事件）
注：同一时间只能有一个控件拥有焦点。
my_widget:SetFocus()
Moderate

SetSlotAlignment​

设置水平和垂直定位的插槽对齐方式。

注：该方法仅在此控件是以下任一控件的子级时才有效：HorizontalBoxSlot、VerticalBoxSlot、OverlaySlot、SizeBoxSlot、ScrollBoxSlot、BackgroundBlurSlot、BorderSlot、ButtonSlot、ScaleBoxSlot、UniformGridSlot、GridSlot。
my_widget:SetSlotAlignment(horizontal_alignment?, vertical_alignment?)

Parameters

TypeParameterDefaultDescription
WidgetHorizontalAlignmenthorizontal_alignment?WidgetHorizontalAlignment.Fill
插槽的水平对齐方式
WidgetVerticalAlignmentvertical_alignment?WidgetVerticalAlignment.Fill
插槽的垂直对齐方式
Optimal

SetSlotCanvasLayout​

将布局设为屏幕上的画布。

注：该方法仅在此控件是画布面板的子级时才有效。

锚点：

my_widget:SetSlotCanvasLayout(location?, size?, anchors_min?, anchors_max?, alignment?)

Parameters

TypeParameterDefaultDescription
Vector2Dlocation?Vector(0, 0)
屏幕位置，或者当锚点拉伸时的左侧和顶部偏移量
Vector2Dsize?Vector(0, 0)
尺寸，或者当锚点拉伸时的右侧和底部偏移量
Vector2Danchors_min?Vector(0, 0)
最小锚点，从 (0, 0) 左上角到 (1, 1) 右下角
Vector2Danchors_max?Vector(1, 1)
最大锚点，从 (0, 0) 左上角到 (1, 1) 右下角
Vector2Dalignment?Vector(0.5, 0.5)
控件的轴心点，(0.5, 0.5) 为中心
Moderate

SetSlotPadding​

设置水平和垂直间距的插槽内边距。

注：该方法仅在此控件是以下任一控件的子级时才有效：HorizontalBoxSlot、VerticalBoxSlot、OverlaySlot、SizeBoxSlot、ScrollBoxSlot、BackgroundBlurSlot、BorderSlot、ButtonSlot、GridSlot。
my_widget:SetSlotPadding(padding_horizontal?, padding_vertical?)

Parameters

TypeParameterDefaultDescription
Vector2Dpadding_horizontal?Vector2D(0, 0)
插槽的水平内边距
Vector2Dpadding_vertical?Vector2D(0, 0)
插槽的垂直内边距
Moderate

SetSlotSize​

设置插槽大小和尺寸规则。

注：该方法仅在此控件是以下任一控件的子级时才有效：HorizontalBoxSlot、VerticalBoxSlot、ScrollBoxSlot。
my_widget:SetSlotSize(size?, slate_size_rule?)

Parameters

TypeParameterDefaultDescription
floatsize?0.0
插槽的尺寸值
WidgetSizeRuleslate_size_rule?WidgetSizeRule.Automatic
插槽的尺寸规则
Moderate

SetVisibility​

设置其在屏幕上的可见性
my_widget:SetVisibility(visibility)

Parameters

TypeParameterDefaultDescription
WidgetVisibilityvisibility Required parameter 屏幕中的新可见性状态

See also GetVisibility.

Slow

SpawnWidget3D​

生成一个在世界中渲染此控件的 3D 控件 Actor
local widget_3D = my_widget:SpawnWidget3D(location?, rotation?, widget_space?, auto_size?, size?, auto_repaint_rate?, pivot?)

Parameters

TypeParameterDefaultDescription
Vectorlocation?Vector(0, 0, 0)
世界位置
Rotatorrotation?Rotator(0, 0, 0)
世界旋转
WidgetSpacewidget_space?WidgetSpace.World
在世界空间中渲染还是始终面向屏幕
booleanauto_size?false
是否根据其内容自动调整尺寸
Vector2Dsize?Vector2D(500, 500)
仅在 auto_size = false 时生效
floatauto_repaint_rate?-1
保持 -1 以在每一帧都重新绘制
Vector2Dpivot?Vector2D(0.5, 0.5)
控件的轴心点，(0.5, 0.5) 为中心

Returns

TypeDescription
Widget3D生成的 Widget3D
Optimal

UnbindBlueprintEventDispatcher​

解绑一个蓝图事件分发器
my_widget:UnbindBlueprintEventDispatcher(dispatcher_name, callback?)

Parameters

TypeParameterDefaultDescription
stringdispatcher_name Required parameter 事件分发器名称
functioncallback?nil
可选的要解绑的回调函数

🚀 事件​

Inherited Entity Events
Widget inherits from Base Entity Class, sharing it's events:
Base Entityscripting-reference/classes/base-classes/entity
NameDescription
ClassRegister当使用 继承系统 注册一个新类时触发
Destroy当实体被销毁时触发
Spawn当实体被生成/创建时触发
ValueChange当实体通过 :SetValue() 改变了值时触发

This class doesn't have own events.

✅ NativeWidgets 与虚幻控件的关系​

虚幻原生 Widget ↔ NativeWidget 枚举的对应关系列表：

枚举虚幻类是否为面板
NativeWidget.BorderBorder✅
NativeWidget.ButtonButton✅
NativeWidget.CheckBoxCheckBox✅
NativeWidget.ImageImage❌
NativeWidget.ProgressBarProgressBar❌
NativeWidget.RichTextBlockRichTextBlock❌
NativeWidget.SliderSlider❌
NativeWidget.TextTextBlock❌
NativeWidget.ComboBoxComboBox❌
NativeWidget.EditableTextEditableText❌
NativeWidget.EditableTextMultiLineMultiLineEditableText❌
NativeWidget.SpinBoxSpinBox❌
NativeWidget.TextBoxEditableTextBox❌
NativeWidget.TextBoxMultiLineMultiLineEditableTextBox❌
NativeWidget.CanvasPanelCanvasPanel✅
NativeWidget.GridPanelGridPanel✅
NativeWidget.HorizontalBoxHorizontalBox✅
NativeWidget.OverlayOverlay✅
NativeWidget.ScaleBoxScaleBox✅
NativeWidget.ScrollBoxScrollBox✅
NativeWidget.SizeBoxSizeBox✅
NativeWidget.UniformGridPanelUniformGridPanel✅
NativeWidget.VerticalBoxVerticalBox✅
NativeWidget.WrapBoxWrapBox✅
NativeWidget.BackgroundBlurBackgroundBlur✅

✅ 支持的参数类型列表​

请在蓝图页面查看所有支持的参数类型。