UE5.8 Common UI 喂饭级专题

UE5.8 Common UI 专题（六）：按钮、Tab、List 和样式

讲清 UCommonButtonBase、CommonButtonStyle、InputActionWidget、锁定态、选中态、Hold、CommonButtonGroup、CommonTabListWidgetBase、CommonListView/TileView/TreeView 的真实用法。

UE5.8 Common UI CommonButton TabList ListView
开始阅读 返回 Unreal 索引

总览

Common UI 的按钮不是普通 UButton 加点皮肤。UCommonButtonBase 把焦点、Hover、Pressed、Selected、Locked、Disabled、输入动作提示、Hold 进度和声音都串起来。手柄项目里，这比自己拼 UButton + Image + Text 稳得多。

UE5.8 Common UI 专题（六）：按钮、Tab、List 和样式 配图
CommonButtonBase 把点击、焦点、选中、锁定、输入提示和长按进度封装成一个适合游戏 UI 的按钮基类。

CommonButtonStyle 负责视觉

UCommonButtonStyle 是按钮样式资产，包含不同状态下的 SlateBrush、TextStyle、Padding、Min/Max 尺寸、声音等。建议项目里先建三类：

Style用途
ButtonStyle_Primary主操作，例如开始、确认
ButtonStyle_Secondary次操作，例如返回、取消
ButtonStyle_TabTab/分页按钮

按钮蓝图继承 CommonButtonBase，根部不用直接放 UButton；CommonButtonBase 内部会构造 UCommonButtonInternalBase。你只需要绑定文本、图标和可选 CommonActionWidget。

选中、锁定、禁用的区别

状态大白话用法
Disabled按钮不可交互，通常灰掉功能不可用
Locked可以 Hover/Focus/Pressed，但不会执行点击未解锁、需购买、等级不足
Selected当前被选中，样式改变Tab、单选项、装备项
Toggleable点击选中项可取消复选风格按钮

DisableButtonWithReason 可以给禁用原因。Locked 有 OnLockClicked，很适合“点击锁定角色弹出解锁条件”。

InputActionWidget 放哪里

CommonButtonBase 有可选绑定控件 InputActionWidget。算法是：

  1. 如果 TriggeringEnhancedInputAction 有值，显示它。
  2. 否则显示 TriggeringInputAction。
  3. 否则显示 TriggeredInputAction。
  4. 否则 Hover 时显示默认 Click Action。

小按钮可以 bHideInputAction=true；键盘下不想显示提示可以 bHideInputActionWithKeyboard=true。

ButtonGroup 和 Tab

多个按钮互斥选择时用 UCommonButtonGroupBase。Tab 页面更推荐 UCommonTabListWidgetBase：

TabList->SetLinkedSwitcher(SettingsSwitcher);
TabList->RegisterTab(TEXT("Video"), TabButtonClass, VideoPanel);
TabList->RegisterTab(TEXT("Audio"), TabButtonClass, AudioPanel);
TabList->RegisterTab(TEXT("Controls"), TabButtonClass, ControlsPanel);
TabList->SelectTabByID(TEXT("Video"));

TabList 可以绑定 Next/Previous Tab 输入。Enhanced Input Support 开启后，还能用 NextTabEnhancedInputAction 和 PreviousTabEnhancedInputAction。

ListView 里的 Entry 也要可聚焦

背包、任务、服务器列表通常用 CommonListView/CommonTileView/CommonTreeView。Entry Widget 建议继承 CommonButtonBase 或内部含 CommonButtonBase，这样手柄焦点、Selected、Clicked 语义一致。

数据流建议：ListView 持有 UObject Item；Entry 在 NativeOnListItemObjectSet 读数据并刷新展示；点击 Entry 后通知页面。不要让 Entry 自己 Push 详情页，页面负责路由更清晰。

使用案例：长按删除存档

删除按钮继承 CommonButtonBase，设置：

  • bRequiresHold=true
  • HoldData 设置 0.8 秒
  • InputActionWidget 用 ProgressMaterialBrush 显示圆环
  • OnActionComplete 执行删除或打开二次确认

这样鼠标、手柄、触摸都能得到一致的长按反馈。

常见坑

  • 用普通 UButton 做 Tab，手柄焦点和选中态要自己补一堆逻辑。
  • 把不可购买按钮 Disabled，玩家无法点它查看解锁条件；这种应当用 Locked。
  • List Entry 没有稳定尺寸，焦点移动时布局跳动。
  • TabList 注册 Tab 后忘记 Select 默认 Tab，Switcher 空白。
  • ActionButton 的文本变量没叫 Text_ActionName，BoundActionButton 不会自动更新文字。

源码依据

UCommonButtonBase 提供 SetIsSelected、SetIsLocked、SetIsSelectable、SetIsToggleable、SetTriggeringEnhancedInputAction、SetRequiresHold、Hold 进度和一系列 BP 事件。源码注释说明 Locked 按钮仍可 Focus/Hover/Pressed，但不广播 Click。UCommonTabListWidgetBase 管理 TabID、TabButton、ContentInstance 和 LinkedSwitcher，并支持 Next/Previous Tab input action。

源码路径索引

  • CommonUI/Public/CommonButtonBase.h
  • CommonUI/Public/CommonButtonGroupBase.h
  • CommonUI/Public/CommonTabListWidgetBase.h
  • CommonUI/Public/CommonListView.h
  • CommonUI/Public/CommonActionWidget.h