UDreamTabView
UDreamTabView
继承自 UDreamUIControl。
声明于 Public/Controls/DreamTabView.h。
一种层级结构由代码而非资产定义的选项卡视图:一栏选项卡位于一个页面切换器之上。
页面从何而来,这是选项卡视图唯一有趣的问题。
该控件拥有切换器,而页面不过是使用者在选项卡视图中嵌套的子级。不会复制任何内容,也不会按名称绑定:放置在宿主树中的 UDreamUserWidget 会保留宿主在其下编写的内容,并且 InitializeWidgetStatic 会运行嵌套实例的 Initialize——因此当 NativeOnInitialized 运行时,这些页面已经位于此控件上。该控件所做的只是在构建自身任何内容之前对它们进行快照,然后将每个页面挂到切换器下。因此,这是一个可用的选项卡视图,来自 .dui,无需其他内容:
Native.TabView Settings {
Widget Video { ... }
Widget Audio { ... }
Widget Controls { ... }
}考虑过、但并非本实现所采用的两种做法:
- NamedSlot。UDreamNamedSlot 只接受一个子项,因此页面外面还得包一层面板;更糟的是,宿主填充槽位这一步位于 InitializeWidgetStatic 内部,受
InWidgetTreeArchetype != nullptr判断保护,而原生类永远没有控件树原型。原生控件根本无法接收命名槽位的内容。 - 将页面做成 TArray 属性。这门语言无法书写容器:非短格式目标上的元组会被直接拒绝(ValueTypeMismatch),而裸字符串也无法为 ImportText 拼出数组。嵌套是 .dui 唯一原生支持的东西,所以嵌套就是那扇门。
标签页从何而来。每个索引对应一个标签页,索引数量取标签数与页面数中较多的一方,因此标签条永远不会比它所驱动的内容更空。当 TabLabels 在该索引处有条目时,由它命名第 i 个标签页;否则标签页就沿用页面自身的节点 id。正是这一回退让上面的文件在完全没有标签列表的情况下也能工作,而 TabLabels 仍是详情面板、蓝图和绑定都能触及的写法:
Native.TabView Settings {
TabLabels <- GetSettingsTabs() // localizable, from the host class
ActiveTabIndex <-> CurrentSettingsTab
...
}同样的容器限制也影响赋值形式 —— TabLabels = (...) 无法解析为数组 —— 因此想要可翻译标签的 .dui 会去绑定它们,而不是内联书写。节点 id 是标识符而非可翻译字符串,这正是该回退刻意保持文化无关、而不是假装可以翻译的原因。
为什么一个标签页是两个视觉件。标签页是一个长得像按钮的单选按钮:各个切换项共享同一个 UUIToggleGroup,因此互斥由该组负责,而不是本控件。但一个 UUISelectable 恰好拥有两个过渡,而标签页需要三种外观 —— 指针状态、选中态和标签。指针过渡给面着色;CHECKED 过渡给覆盖其上的一块独立满幅板着色(若都作用于同一个视觉件,它们会互相覆盖,选中色只会维持到下一次悬停 —— 这正是切换项盒子与勾选分离的翻版);而标签颜色已无过渡可用,因此由控件直接推送。三种外观,两个过渡,一次显式推送。
肩键用于切换标签页(IDreamUITabSwitchTarget):项目配置的 PreviousTabKeys 和 NextTabKeys(默认为 LB 和 RB)会找到玩家焦点所在的标签视图 —— 若没有,则找到其当前活动屏幕上的第一个 —— 并切换到上一个或下一个已启用的标签页,在两端循环,与 CommonUI 的标签列表一致;只要存在这样的标签视图,操作栏就会显示这两个提示。
属性
| 名称 | 类型 | 类别 | 在细节面板中 | 来自蓝图 | 描述 |
|---|---|---|---|---|---|
Style | FDreamTabViewStyle | Tab View | 是 | SetStyle | 此实例自身的外观。当 StyleSource 指示如此且项目样式表实际存在时,项目样式表优先;如果项目中没有任何样式表,则这就是生效的外观——这就是为什么它保持可编辑而不是由枚举来限制:旧的编辑条件会将正在驱动控件的那些确切值置灰。 |
TabLabels | TArray<FText> | Tab View | 是 | SetTabLabels | 选项卡标题,按索引与页面匹配。条目为该选项卡命名;缺失或为空则让该选项卡显示其页面的节点 id(见类注释)。允许长度超过页面列表,并会扩展选项卡栏——一个在页面之前编写选项卡的界面应当能看到它正在构建的选项卡栏。 |
ActiveTabIndex | int32 | Tab View | 是 | GetActiveTabIndex / SetActiveTabIndex | 哪个选项卡处于打开状态,即切换器显示哪个页面。这是一个属性,而不仅仅是 getter/setter 对,因为仅凭这对函数是不可见的:.dui 写入属性,设计器列出属性,绑定解析属性。 |
TabTemplateClass | TSubclassOf<UDreamUserWidget> | Tab View | 是 | SetTabTemplateClass | 选项卡的内容,在别处编写:该类的每个选项卡控件内部都会创建一个实例,填充它,内置标签则让位。选项卡的外观、其选中底板、其悬停状态及其在切换组中的位置仍由控件掌控,因此模板只需绘制一个选项卡。 |
TabEnabled | TArray<bool> | Tab View | 是 | SetTabEnabledStates | 哪些选项卡可被选中,按索引与选项卡栏匹配——与 TabLabels 使用的相同并行数组惯用法,也是出于同样的原因:如果每个选项卡使用一个结构体,会让常见情况(完全没有意见)付出语言无法编写的数组字面量代价。 |
bTabsClosable | bool | Tab View | 是 | SetTabsClosable | 每个选项卡都带有关闭按钮,点击一个即关闭该选项卡——浏览器的做法。 |
bTabsDraggable | bool | Tab View | 是 | SetTabsDraggable | 选项卡可沿选项卡栏拖动以重新排序,并携带其页面一起移动。 |
bFocusPageOnTabChange | bool | Tab View | 是 | SetFocusPageOnTabChange | 切换选项卡会将焦点移入新页面。 |
BodyNode | TObjectPtr<UDreamWidget> | Tab View | - | 只读 | 各个部分,以框架其余部分预期找到它们的形状呈现。 |
StripNode | TObjectPtr<UDreamWidget> | Tab View | - | 只读 | |
IndicatorNode | TObjectPtr<UDreamWidget> | Tab View | - | 只读 | 打开选项卡下方的线条。忽略布局;此控件是唯一放置它的东西。 |
PageHostNode | TObjectPtr<UDreamWidget> | Tab View | - | 只读 | 页面区域:切换器的控件,以及绘制页面背景的面板。 |
PageSwitcher | TObjectPtr<UDreamLayoutContainerWidgetSwitcher> | Tab View | - | 只读 | |
TabGroup | TObjectPtr<UUIToggleGroup> | Tab View | - | 只读 | 互斥,整体借用自单选按钮的机制。 |
Tabs | TArray<FDreamTabViewTab> | Tab View | - | 只读 | 选项卡栏中每个选项卡一个条目,按选项卡栏顺序排列。 |
函数
| 函数 | 类型 | 描述 |
|---|---|---|
void AddPage(UDreamWidget* InPage) | 可调用 | 将一个控件作为下一个页面放入,用于在代码而非 .dui 中组装的界面。选项卡栏会重新生成,因此添加超过 TabLabels 末尾的页面仍会得到一个选项卡。 |
void CloseTab(int32 InIndex) | 可调用 | 关闭一个选项卡:广播,然后丢弃其标题并销毁其页面,再重新生成选项卡栏。 |
UDreamWidget* GetActivePage() | 纯函数 | 切换器正在显示的页面,或者在附加任何页面之前为 null。 |
int32 GetActiveTabIndex() | 纯函数 | 获取活动选项卡索引 |
UDreamWidget* GetPage(int32 InIndex) | 纯函数 | 获取页面 |
int32 GetPageCount() | 纯函数 | 切换器持有的页面数量。不一定是选项卡栏显示的选项卡数量。 |
bool IsTabEnabled(int32 InIndex) | 纯函数 | 缺失条目表示启用——见 TabEnabled。 |
void MoveTab(int32 InFromIndex, int32 InToIndex) | 可调用 | 移动一个选项卡,携带其页面。两个索引都基于当前的选项卡栏。选项卡的控件随之移动,而不是重建选项卡栏,当移动改变了打开的选项卡时,OnTabChanged 会报告其新索引。 |
void SetActiveTabIndex(int32 InIndex) | 可调用 | 打开一个选项卡。当索引实际移动时广播,与点击该选项卡的行为完全一致。 |
void SetActiveTabIndexWithoutNotify(int32 InIndex) | 可调用 | 相同的移动但不广播。<-> 语法糖正是查找这个名称(setter 加上 "WithoutNotify"),因此双向绑定的正向部分无法回传到刚刚驱动它的变量中。 |
void SetFocusPageOnTabChange(bool bInFocusPageOnTabChange) | 可调用 | 设置选项卡更改时聚焦页面 |
void SetStyle(FDreamTabViewStyle InStyle) | 可调用 | 替换外观并推送它。 |
void SetTabEnabled(int32 InIndex, bool bInEnabled) | 可调用 | 在需要时扩展 TabEnabled 以到达 InIndex,然后重新推送选项卡栏的颜色。禁用拥有焦点的选项卡会将其移动到该选项卡的右侧邻居,否则移动到最后一个启用的选项卡。 |
void SetTabEnabledStates(TArray<bool> InTabEnabled) | 可调用 | 一次性设置每个选项卡的启用标志;缺失条目表示启用。SetTabEnabled 更改一个。 |
void SetTabLabels(TArray<FText> InLabels) | 可调用 | 替换标题并重新生成选项卡栏。 |
void SetTabsClosable(bool bInTabsClosable) | 可调用 | 显示或隐藏每个选项卡的关闭按钮。这是一种重新样式化:按钮在样式循环中被唤醒。隐藏它们会先将焦点从按钮上移到其选项卡上。 |
void SetTabsDraggable(bool bInTabsDraggable) | 可调用 | 设置选项卡可拖动 |
void SetTabTemplateClass(TSubclassOf<UDreamUserWidget> InTabTemplateClass) | 可调用 | 编写的选项卡内容。在构建时实例化到每个选项卡中,因此新的类意味着重建。 |
事件
| 事件 | 签名 | 描述 |
|---|---|---|
OnTabGenerated | void DreamTabViewTabEvent__DelegateSignature(int32 TabIndex, UDreamWidget* Tab) | 在构建选项卡条时为每个选项卡触发一次。对于选项卡内容比一个词更丰富、但又不愿编写整个类的使用者来说,这是一个钩子:选项卡下的所有内容都可以通过显示名称从这里访问。这是列表的 OnRowGenerated 在选项卡视图中的对应物。 |
OnTabChanged | void DreamTabViewChangedEvent__DelegateSignature(int32 ActiveTabIndex) | 当打开的选项卡发生变化时触发,无论由谁更改——点击、SetActiveTabIndex,还是关闭或重排序导致其移动。使用者绑定到此事件,而不是绑定到某个选项卡。 |
OnValueChangedBP | void DreamTabViewChangedEvent__DelegateSignature(int32 ActiveTabIndex) | <-> 约定:双向绑定会针对这个确切的名称合成其反向路由,因此值控件会将其与自身的显式事件一起携带。它会与这些事件一同触发。 |
OnTabClosed | void DreamTabViewChangedEvent__DelegateSignature(int32 ActiveTabIndex) | 某个选项卡正在关闭。在页面被销毁、标题被移除之前触发,因此想要保留该页面的使用者可以在此将其从切换器中取出——这与 UDreamDialog::Close 的广播顺序相同,原因也相同。 |
OnTabReordered | void DreamTabViewReorderEvent__DelegateSignature(int32 FromIndex, int32 ToIndex) | 某个选项卡被拖动到了新位置。两个索引都是相对于移动前的选项卡条而言的。 |