导图社区 CommonUI教程内容梳理
学习并梳理了Vince Petrelli大佬在udemy上的CommonUI视频教程,包含了教程中所涉及的关于UE C 和蓝图的知识点,并整理了一系列相关的C 库文件在虚幻引擎编程中所起到的作用,教程在B站有大佬翻译。
编辑于2025-09-11 20:48:53UE C++ CommonUI
使用的插件
Common UI
组件堆栈
用来管理组件层级
组件池
用来避免频繁create/remove组件
CommonUserWidget
CommonUI基础类
仅包含一些基本的帮助输入的函数
不能进堆栈
动作绑定
RegisterUIActionBinding
RemoveActionBinding
GetActionBindings
AddActionBinding
CommonActivatableWidgetStack
自带widget进栈出栈的过渡效果
CommonActivableWidget
可以进栈
可以切换激活状态
可以return到它
UCommonActivatableWidgetContainerBase
可以存放CommonActivableWidget的控件堆栈
Common Text
可以应用style资产
CommonRichTextBlock
文本
<Bold>这是一个描述</>
样式
Common Button
可以应用style资产
可以触发自定义输入
比如用键盘触发屏幕上的按钮
可以自动响应输入方式的切换
比如从键盘切换到手柄
支持手柄导航
CommonBoundActionBar
自带手柄导航支持
CommonBoundActionButton
用户界面可以将输入操作映射到屏幕上的按钮
CommonActionWidget
根据输入设备和平台动态显示对应的图标
CommonInputSubsystem
管理Gamepad, Mouse, keyboard 的输入模式
项目设置
游戏视口客户端类
游戏视口客户端类(Game Viewport Client Class) 是负责管理游戏视口(Viewport)行为与功能的核心类,它是连接游戏渲染输出、用户输入和游戏逻辑的重要桥梁。
默认情况下,UE 使用内置的 UGameViewportClient 类作为基础实现。如果项目需要自定义视口行为(如特殊的输入处理、分屏逻辑或渲染效果),可以创建 UGameViewportClient 的子类,重写其方法(如 OnViewportResized、ProcessInput 等),然后在「项目设置 > 地图与模式 > 默认类」中指定为新的默认游戏视口客户端类。
简单来说,这个类是游戏视口的「管理者」,负责协调视口的显示、输入和与游戏逻辑的交互,是定制游戏画面交互体验的重要入口。
高级输入系统
user settings
启动用户设置
将IMC中的按键注册到EnhancedInputUserSettings
可以实现运行中更改按键映射
UE C++知识点
UE宏
GameplayTags
UE_DECLARE_GAMEPLAY_TAG_EXTERN :在 .h 文件中用于声明 .cpp 文件中定义的标签。
UE_DEFINE_GAMEPLAY_TAG :在 .cpp 文件中用于定义 .h 文件中声明的标签,不带提示文本注释。
UE_DEFINE_GAMEPLAY_TAG_COMMENT :在 .cpp 文件中用于定义 .h 文件中声明的标签,带有提示文本注释。
UPARAM
meta
Categories = ""
可以用来过滤类别符合“”中的变量(包括GameplayTag)
ForceInlineRow
强制TMap属性里的结构key和其他Value合并到同一行来显示
BindWidget
强制要求此Widget指针在其蓝图子类实例化前指定组件
要确保被指定的控件名称要与指针名称一致
如果没有指定,Widget蓝图编译会失败
BindWidgetOptional
不要求此Widget指针在其蓝图子类实例化前指定组件
要确保被指定的控件名称要与指针名称一致
如果没有指定,Widget蓝图编译依然会成功
UPROPERTY
Config
UPROPERTY 宏的 Config 元数据说明符用于将变量与配置文件(.ini 文件) 关联,实现变量值的持久化存储与外部修改,核心作用是允许在不重新编译代码的情况下调整参数,同时保证参数值在引擎重启后仍能保留。
在头文件中设置默认值无效
如果要让蓝图能访问拥有Private 权限的属性,需要在其的meta说明符中加入AllowPrivateAccess = true
FORCEINLINE
强制编译器执行内联,除非存在无法内联的特殊情况
LIST_DATA_ACCESSOR
#define LIST_DATA_ACCESSOR(DataType,PropertyName) \ FORCEINLINE DataType Get##PropertyName() const {return PropertyName;} \ void Set##PropertyName(DataType In##PropertyName) {PropertyName = In##PropertyName;}
GET_FUNCTION_NAME_STRING_CHECKED
根据输入的 “类名” 和 “函数名”,在编译时检查该类中是否确实存在这个函数;若存在,则返回该函数的名称字符串;若不存在,则直接触发编译错误。
元数据说明符
DisableNativeTick
禁用对象参与引擎的原生 Tick 循环
即使对象的 Tick 相关设置(如 bCanEverTick)为启用状态,引擎也不会自动触发其 Tick 函数。
meta = (WorldContext = "WorldContextObject", HidePin = "WorldContextObject")
BlueprintInternalUseOnly
表示该变量只能在蓝图类的成员函数中进行读写操作。常用于定义只能在类内部访问的变量。
BlueprintAssignable
应显示该属性,以供在蓝图中分配,蓝图中可绑定委托
编程子系统
Subsystems 是一套可以定义、自动实例化和释放的类的框架。可以将其理解为 GamePlay 级别的 Component 不支持网络赋值
五种类型
UEngine* GEngine; UEditorEngine* GEditor; UGameInstance* GameInstance; UWorld* World; ULocalPlayer* LocalPlayer;
TFunction
TFunction是一个通用的函数对象封装器,允许将任何可调用的对象(例如lambda表达式、函数指针、成员函数等)存储在一个统一的对象中,然后通过该对象进行调用。
例子
TFunction<bool (int32)> MyFunc = [](int32 SomeParam)->bool{}
指针
弱对象指针TWeakObjectPtr
软类指针
LoadSynchronous
TSharedPtr共享指针
MakeShared
开发者设置
DeveloperSettings
FText
FText没有重载operator==,相关的运算也不可用
UClass
本质上是一个描述 UObject 派生类元数据的类。它存储了类的各种信息(如类名、父类、属性、函数、蓝图配置等),并在运行时提供对这些信息的访问能力
&ThisClass
UE反射系统 ThisClass 本质上是当前类的 “自引用别名”,用于替代类名本身,尤其在需要访问类的 UClass 指针(UE 反射系统的核心,用于描述类的元数据)时非常方便。
Widget
UListView
virtual void ValidateCompiledDefaults(class IWidgetCompilerLog& CompileLog)
UWidget里的函数
可以重写实现确保特定的变量在未指定时编译报错
TOptional
TOptional 是一个模板类(定义于 CoreMisc.h),用于表示一个 “可选值”—— 即某个值可能存在,也可能不存在。它的核心作用是提供一种类型安全的方式来处理 “值可能缺失” 的场景,避免使用空指针(nullptr)或特殊默认值(如 -1、0)带来的歧义与风险
TRange
TRange 是一个模板类(定义于 CoreTypes.h),用于表示一个数值范围(如整数、浮点数等),支持灵活定义 “上下边界” 及 “边界是否包含” 的规则(如闭区间 [1,10]、开区间 (2,5) 等)。它的核心价值是提供标准化的范围操作(如判断值是否在范围内、求交集 / 并集等),简化涉及 “区间” 逻辑的代码
FCoreUObjectDelegates
FCoreUObjectDelegates 是一个全局的委托集合类,用于管理 UObject 系统核心事件的回调。它定义了一系列与 UObject 生命周期(如加载、卸载、垃圾回收、序列化等)相关的多播委托
比如地图预加载和加载完成
注意事项
所有的基类都要有UCLASS(ABSTRACT, BlueprintType, meta = (DisableNativeTick))
所有对象指针在函数中被使用前都要验证其有效性
头文件总结
#include "Engine/AssetManager.h"
包含引擎中用于管理资源(如纹理、模型等)的 AssetManager 类声明的头文件,提供资源加载、存储和访问等功能。
#include "Widgets/CommonActivatableWidgetContainer.h"
用于管理 “Activatable Widget” 的容器类头文件,支持 “激活 / 停用” 状态切换,并能自动处理输入焦点、输入模式切换等逻辑
#include "GameplayTagContainer.h"
用于存储和管理多个 Gameplay Tag 的集合类
#include "ICommonInputModule.h"
ICommonInputModule
ICommonInputModule 是 CommonInput 模块的核心接口类(继承自 IModuleInterface),负责管理 CommonInput 模块的生命周期,并提供访问模块核心功能(如输入设备配置、CommonInputSubsystem 实例等)的入口
UDynamicEntryBox
专门用于动态生成和管理重复 UI 条目的容器控件
FDataTableRowHandle
FDataTableRowHandle 是一个用于引用数据表中特定行数据的结构体
#include "Blueprint/IUserObjectListEntry.h"
IUserObjectListEntry 接口类的头文件。这个接口是 UMG(Unreal Motion Graphics)系统中列表控件(如 UListView、UDataGridView)与条目 Widget 之间数据绑定的核心桥梁,用于定义 “列表条目” 如何接收和处理来自列表数据源的数据
UDataAsset
UDataAsset 是一种用于存储静态配置数据的资源类(继承自 UObject),专门用于实现 “数据驱动开发”—— 将游戏中的静态数据(如角色属性、技能参数、UI 配置等)与代码逻辑分离,允许在不修改代码的情况下通过编辑器直接调整数据
UGameUserSettings
用于管理和持久化玩家游戏设置的核心类,并确保这些设置在游戏重启后仍能保持生效
#include "PropertyPathHelpers.h"
属性路径(Property Path)工具类 的头文件,核心包含 FPropertyPathHelpers 等辅助结构体 / 函数。它的核心作用是简化 UE 反射系统中 “嵌套属性的路径解析与访问”—— 即通过字符串路径(如 "Player.Stats.Health")动态定位并操作 UObject 及其嵌套属性(如成员变量、结构体字段),无需硬编码层级访问逻辑
KismetSystemLibrary
提供了大量通用的工具函数,用于简化蓝图(及 C++)开发中的常见任务。它涵盖了对象管理、数组操作、字符串处理、日志输出、世界交互等
#include "CommonInputBaseTypes.h"
包含了 CommonInput 系统的核心枚举、结构体和常量
UCommonInputPlatformSettings
是 CommonInput 模块中用于存储特定平台输入配置的类
#include "Framework/Application/IInputProcessor.h"
IInputProcessor 接口类的头文件。该接口是 UE Slate 应用框架 中处理低级别输入事件的核心抽象,允许开发者自定义输入处理逻辑,并插入到引擎的输入处理链中,实现对键盘、鼠标、触摸等输入事件的拦截、修改或扩展
#include "CommonUITypes.h"
包含了 CommonUI 系统(跨平台 UI 开发框架)中通用的枚举、结构体和常量,确保 UI 行为(如激活逻辑、层级管理、输入响应)的一致性
#include "Internationalization/StringTableRegistry.h"
负责全局管理所有字符串表(String Table)资源,包括注册、查找、加载和卸载字符串表,是本地化文本(多语言支持)功能的基础支撑
蓝图知识点
控件层级
同一层级内,最顶层的显示在最低下,最底层的显示在最上面
异步动作
蓝图异步动作类(Blueprint Async Action Class) 是一种专门用于处理异步操作的蓝图, 可以作为使用此类来调用C++中自定义的动作类来使用
取色器基于的是三维坐标系下的极坐标
使用多播委托实现多个pin
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnPushSoftWidgetDelegate, UWidget_ActivatableBase*, PushedWidget);//声明委托
类中: UPROPERTY(BlueprintAssignable) FOnPushSoftWidgetDelegate OnWidgetCreatedBeforePush; UPROPERTY(BlueprintAssignable) FOnPushSoftWidgetDelegate AfterPush;
UserWidget作为模板
namedSlot
Override
Widget
GetDesiredInputConfig
enhanced input
Register Input Mapping Context
Add Mapping Context
命名规范
C++
所有继承自CommonUserWidget的类,前面都要加Widget_
所有override的函数,其前后注释要表明函数出处,并且要表明原函数所在的类
例子
//Begin USubsystem Interface virtual bool ShouldCreateSubsystem(UObject* Outer) const override; //End USubsystem Interface
override函数的权限应与原函数在其类中的权限保持一致
函数参数中作为输入值的前缀要加In,作为输出值的前缀要加Out
声明Widget的meta说明符中有BindWidget或BindWidgetOptional的语句,其前后需要用//**** Bind Widget ****//来标明
例子
//**** Bound Widgets ****// UPROPERTY(meta = (BindWidgetOptional)) UCommonTextBlock* CommonTextBlock_ButtonText; UPROPERTY(BlueprintReadOnly, meta = (BindWidgetOptional, AllowPrivateAccess = "true")) UCommonLazyImage* LazyImage_ButtonImage; //**** Bound Widgets ****//
蓝图
WBP代表控件蓝图+_+CUW(父类首字母大写)+_+蓝图名
教程大纲
创建堆栈
四个堆栈
Model Stack
Pop Up2
Pop Up1
Game Menu Stack
Pause Menu
Inventory
Game Hud Stack
Health Bar
Frontend Stack
Frontend Menu
更高层级的控件总能deactive更低层级的控件
使用GameplayTag来识别控件类型
通过FrontUISubsystem广播Description文本
异步加载
异步加载
在FrontendUISubSystem中实现UI异步加载逻辑
UBlueprintAsyncActionBase用来实现蓝图异步加载节点
软加载Widget
显示主菜单
使用蓝图节点异步加载对应的Widget
使用Developer Setting保存Widget_GameplayTag 和软加载Widget类型的映射
创建布局模版
使用namedSlot来实现布局在其他widget中的复用
实现绑定动作栏
设置Action Bar
设置action button widget蓝图
设置默认按键
设置数据表
涉及的类
数据表行:CommonInputActionDataBase
CommonUIInputData
CommonInputBaseControllerData
涉及的开发者设置
通用输入设置
手柄名要设置成Generic
显示确认屏幕
要求
蓝图+C++
动态生成且模块化
不处理真实逻辑
告知点击结果
涉及的类
UDynamicEntryBox
声明了UConfirmScreenInfoObject
工厂类
FDataTableRowHandle
结果
生成一个蓝图异步操作来调用确认窗口
自定义按键动作绑定
涉及函数
RegisterUIActionBinding()
涉及的结构体
FBindUIActionArgs
方法
将自定义动作插入到绑定动作栏的方法
RegisterUIActionBinding( FBindUIActionArgs( ResetAction, true, FSimpleDelegate::CreateUObject(this, &ThisClass::OnResetBoundActionTriggered) ) );
简单委托
FSimpleDelegate
选项菜单创建
UCommonTabListWidgetBase
ValidateCompiledDefaults
Next/Previous Tab Input Action Data
Link switcher
列数据创建
ListDataObject_Base
ListDataObject_Collection
etc..
概念
富文本
顶部菜单实现
选项菜单
数据寄存
创建tab栏对象
为每个tab内的数据创建对象
涉及的函数
重载
handleTabCreation
菜单选项界面
List data Object
List Entry Object
继承自IUserObjectListEntry
UListView
TArray<UObect*> ListSourceItem
OnGenerateEntryWidgetInternal
创建一个数据寄存对象
处理所有关于数据的逻辑
向listwidget添加内容
使用一个数据资产来记录对应的widget
每一个ListDataObject都对应着一个ListEntryWidget
使用virtual void NativeOnListItemObjectSet(UObject* ListItemObject) override;来修改Entry内容
当特定的TabSelected时
调用对应的寄存对象来更新组件
GenerateTypedEntry
处理旋转器标签
使用ListDataObject_String来存储当前的值
由ListDataObject_String确定当前显示哪一项
因为旋转器中与此相关的函数不好用
使用委托更新旋转器的属性
持久化用户选项
UGameUserSettings
可以将属性持久化
同时如让音量修改,难度修改等逻辑生效的代码也放在此处
创建通用的方法来保存数据到UserSetting
GameuserSetting中创建Getter和Setter
创建一个FOptionDataInteractionHelper(继承自PropertyPathHelpers)来获取函数路径并修改data值
ListDataObject_String创建动态获取器,通过FOptionDataInteractionHelper来建立对应函数的联系
PropertyPathHelpers::SetPropertyValueFromString
切换listentry选中状态
自定义蓝图函数触发Hovered
CastChecked<UListView>(GetOwningListView())->SetSelectedItem(GetListItem());
使user在点击条目内控件时也能触发listentry的选择
添加详情面板
需求
title
Description Image
Description text
dynamic details
Disabled Reason
选项重置
设置默认值
UGameUserSettings
收集可重置数据
动作绑定
RegisterUIActionBinding
RemoveActionBinding
GetActionBindings
AddActionBinding
自定义区域聚焦
UWidget和SWidget
头部列表项
仅用于区分不同类别
不可选、不可导航
直接使用Collection作为头部列表,有dataMapping来决定对应的Widget
滑块EntryWidget(标量)
Widget
comonText
CommonNumeric Text Block
Analog Slider
listdataobject
数字格式
滑块的最大最小值
display range和output range
映射显示值和实际值
boolEntryWidget
继承自ListDataObject_String
将TrueString和FalseString添加到StringArray中
反正真正的生效逻辑放在了GameUserSetting中,所以大部分逻辑可以与ListDataObject_String保持一致
字符串枚举类型
StaticEnum
模板函数,用于获取 C++ 中通过 UENUM() 宏声明的枚举类型对应的反射元数据对象(UEnum*),允许开发者在运行时动态访问枚举的元数据
字符串分辨率类型
KismetSystemLibrary
GetSupportedFullscreenResolutions获取所有当前屏幕可用的分辨率
打包构建
运行基准测试
list数据间实现依赖编辑
创建编辑条件
加载依赖数据
通过委托绑定,当目标list项被触发时,触发当前项的依赖修改委托
修改widget_listentry可编辑状态
字符串整数数据对象
将整数转换为string类型存储进数组中
字符串表
使用LOCTABLE宏,输入Stringtable文件地址和key来获取对应的FText
#include "Internationalization/StringTableRegistry.h"
control菜单实现(按键菜单)
按键重定向
集合所有可用的按键
使用高级输入系统(ue5中此系统已取代之前的输入系统)
register IMC into usersetting
从user settings中获得所有可用按键
GetAllSaveKeyFiles 已经被替换为了GetAllAvailableKeyProfiles
显示在菜单中
依然是使用ListDataObject和对应的widget_ListEntry来实现
listDataObject_Keymapping
Widget_ListEntry_KeyRemap
重定向
点击对应的项,弹出一个界面监听按键,并将其重定向
注册输入预处理器
Unreal输入处理
输入设备->FSlateApplication->GameViewprotClient
在FSlateApplication中自定义输入注册预处理器
涉及的类
FPlayerMappableKeyQueryOptions
用于配置玩家可映射按键查询条件的结构体
在查询这些可映射按键时,通过设置过滤条件,精确获取需要的按键映射信息
IInputProcessor
加载菜单实现
developer Setting
创建LoadingWidget
创建一个子系统来管理
用来接收Map的加载委托信号
涉及知识点
FCoreUObjectDelegates
FTickableGameObject
//~ Begin FTickableGameObject Interface virtual UWorld* GetTickableGameObjectWorld() const override; virtual void Tick(float DeltaTime) override; virtual ETickableTickType GetTickableTickType() const override; virtual bool IsTickable() const override; virtual TStatId GetStatId() const override; //~ End FTickableGameObject Interface
RETURN_QUICK_DECLARE_CYCLE_STAT
用于快速声明和跟踪循环性操作性能统计的宏,简化代码中高频重复执行的操作(如循环、帧更新函数等)的性能数据收集,方便在 UE Profiler 等工具中分析其耗时和调用频率
STATGROUP_Tickables
预定义的性能统计组(Stat Group),专门用于归类和跟踪可执行 Tick 操作的对象(Tickable Objects)的性能数据。它属于 UE 性能分析系统(Stats System)的一部分,主要帮助开发者监控和优化那些需要每帧更新或定期更新的对象的性能开销
PreLoadScreenManager
负责管理预加载屏幕的系统级管理器类,主要用于在游戏关键资源加载过程中(如关卡切换、大型资产加载时)显示过渡界面
制作人员名单
用定时器驱动ScrollBox的Offset就行