4.8 KiB
4.8 KiB
StyleTokens
命名空间: XCEngine::Editor::UI
类型: header-helper + struct
源文件: editor/src/UI/StyleTokens.h
描述: 集中定义 Editor UI 的颜色、尺寸、间距与树视图样式，是当前编辑器设计系统的单一 token 源。
概述
StyleTokens.h 是当前 Editor UI 的设计语言中心。它把原本最容易散落在各个面板、各类 helper 和临时控件中的“魔法数字”集中成一组具名 token，让代码能够表达设计意图，而不是只暴露数值本身。
例如：
ProjectNavigationDefaultWidth()表达的是“项目导航栏默认宽度”。InspectorPropertyControlColumnStart()表达的是“Inspector 控件列起点”。PanelSplitterHitThickness()表达的是“splitter 命中区宽度”。
这比直接写 248.0f、236.0f、4.0f 更接近商业编辑器的工程实践，因为当 UI 逐步复杂起来后，真正难维护的从来不是控件本身，而是这些散落的视觉约束。
当前 token 分组
按 editor/src/UI/StyleTokens.h 的实现，当前 token 大致可以分成下面几类：
| 类别 | 代表 token | 主要消费者 |
|---|---|---|
| Dock host / tab | DockHostFramePadding()、DockTabSelectedColor() |
DockHostStyle、DockTabBarChrome |
| 面板与工具栏 | PanelWindowPadding()、ToolbarPadding() |
PanelChrome、各类 panel toolbar |
| Project 浏览器 | ProjectNavigationDefaultWidth()、AssetGridSpacing() |
ProjectPanel、Widgets |
| TreeView 导航树 | NavigationTreeIconSize()、NavigationTreePrefixWidth() |
TreeView、HierarchyPanel、ProjectPanel |
| Inspector / 属性布局 | InspectorPropertyControlColumnStart()、ControlFramePadding() |
PropertyLayout、ScalarControls、VectorControls、PropertyGrid |
| Popup / Combo | PopupWindowPadding()、ComboPopupBackgroundColor() |
Core、Widgets |
| 资产卡片与图标 | AssetTileSize()、BuiltInFolderIconBodyColor() |
Widgets、BuiltInIcons |
| Console / 状态栏 | ConsoleRowHoverFillColor()、MenuBarStatusIdleColor() |
Widgets、菜单栏与 Console UI |
此外，StyleTokens.h 里还定义了：
struct TreeViewStyleNavigationTreeStyle()HierarchyTreeStyle()ProjectFolderTreeStyle()
它们是树视图层的“组合 token”，不是单个数值，而是一组可复用的树节点视觉约束。
当前实现行为
按当前源码，这一层有几个很重要的特点：
- token 目前全部是 header-only inline 函数，不是配置资产，也不是运行时可热更新的数据表。
- 很多 helper 会把这里的 token 当默认值，而不是自己再声明一套局部常量。
PropertyLayout、SplitterChrome、DockTabBarChrome、BuiltInIcons、Widgets都直接依赖这里的 token。- 某些 token 之间存在设计上的复用关系，例如
PanelDividerColor()当前直接复用 splitter 的 idle 颜色。
这意味着 StyleTokens.h 不是“装饰性文件”，而是整个 Editor UI 复用层的上游依赖。
设计说明
为什么这层很重要？
- 当你在重构
ProjectPanel时，不应该顺手发明一套新的资产卡片尺寸。 - 当你在做
HierarchyPanel的树前缀图标时，不应该自己再决定一套图标槽宽。 - 当你在优化 Inspector 的密度时，真正应该改的是 token，而不是 5 个不同 helper 里的重复常量。
这就是商业级编辑器常说的“设计系统落地到代码层”的意义。对于 XCEngine 来说，这一层还没有演化成完整的主题资产系统，但它已经承担了相同的架构角色。
与其他 UI helper 的关系
PropertyLayout使用它定义属性行的列宽、label inset 和 frame padding。TreeView使用它定义缩进、前缀插槽宽度和图标尺寸。SplitterChrome与DividerChrome使用它定义边界线和分隔条视觉。Widgets使用它定义资产卡片、面包屑、组件 section 和各种通用控件的视觉细节。BuiltInIcons使用它定义文件 / 文件夹 fallback 图标颜色。
从依赖方向上说，这一层应该尽量保持在 UI 栈的较底部，避免反向依赖更高层的业务 widget。
当前限制
- 当前仍然是“写死在代码里的默认主题”，不是运行时可切换的主题资源系统。
- token 命名已经带有明显的面板语义，例如
ProjectNavigationPanePadding()，说明它还是偏应用内设计系统，而不是完全抽象的通用 design token。 - 还没有颜色模式切换、用户主题文件或样式编辑器一类更高阶能力。