CommonUI教程内容梳理

学习并梳理了Vince Petrelli大佬在udemy上的CommonUI视频教程，包含了教程中所涉及的关于UE C 和蓝图的知识点，并整理了一系列相关的C 库文件在虚幻引擎编程中所起到的作用，教程在B站有大佬翻译。

UE 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就行