主题与样式

界面好不好看，很大程度上取决于颜色和排版。HiEasyX 内置了一套现代化的主题系统，让你不需要写一堆颜色常量，也能做出专业水准的界面。

快速开始：应用主题

一行代码，整个世界都不一样了：

HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);   // 现代暗色（高对比）
// 或者
HX::ApplyModernTheme(HX::HXThemeMode::ModernDim);    // 柔和暗色（护眼）

💡 应该选哪个主题？

• ModernDark：对比度高、清晰锐利，适合演示、截图、短视频录制
• ModernDim：对比度适中、色彩柔和，适合长时间盯屏幕的编辑器、IDE 场景

当然，你也可以在程序运行时动态切换，做一个"主题切换"按钮给用户。

SetThemeMode 与 ApplyModernTheme 的区别

函数	作用
SetThemeMode(mode)	只设置一个枚举标记，不修改任何颜色值
ApplyModernTheme(mode)	根据模式，完整填充 HXTheme 的所有颜色、字体、间距字段

如果你只想切换模式标记（比如在保存配置时记录用户偏好），用 SetThemeMode；如果你想真正改变界面外观，用 ApplyModernTheme。

// 初始化时应用主题
HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);

// 运行时切换主题
if (HX::Button(HXStr("切换主题"), bp)) {
    static bool isDark = true;
    if (isDark) {
        HX::ApplyModernTheme(HX::HXThemeMode::ModernDim);
        isDark = false;
    } else {
        HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);
        isDark = true;
    }
}

---

HXTheme 结构体详解

HXTheme 是 HiEasyX 主题系统的核心。它里面定义了几乎所有控件会用到的视觉参数。下面是主要字段的分类介绍：

基础颜色

字段	类型	说明
Background	HXColor	全局背景色（窗口底层）
Surface	HXColor	面板表面色（窗口内容区背景）
WindowTitleBackground	HXColor	窗口标题栏背景
WindowTitleText	HXColor	窗口标题栏文字
Border	HXColor	通用边框色

控件颜色

字段	类型	说明
ButtonBackground	HXColor	按钮默认背景
ButtonOnHoverBackground	HXColor	按钮悬停背景
ButtonOnHoverBorder	HXColor	按钮悬停边框
TextColor	HXColor	普通文字颜色
TextSecondary	HXColor	次要文字（提示、灰色标签）

强调色与语义色

字段	类型	说明
Accent	HXColor	主题强调色（选中、高亮、主按钮）
Success	HXColor	成功/通过状态
Warning	HXColor	警告状态
Error	HXColor	错误状态

字体与尺寸

字段	类型	说明
FontSize	int	全局基准字号，默认 18
RoundRadius	int	控件圆角半径
Spacing	int	控件之间的默认间距

ℹ️ 关于颜色值

HiEasyX 使用 HXColor 类型表示颜色，通常可以用 HXRGB(r, g, b) 或 HXRGBA(r, g, b, a) 构造。主题中的颜色定义了整个 UI 的"基调"，控件不会随便硬编码颜色，而是尽量从主题中读取。

---

如何自定义主题颜色

ApplyModernTheme 只是起点。如果你想打造自己品牌的配色，可以直接修改 HXTheme 的各个字段。

方式一：在应用主题后微调

// 先加载一套完整的现代主题
HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);

// 再修改个别字段，打造自己的风格
HX::HXTheme& theme = HX::GetTheme();
theme.AccentPrimary = HXColor{0, 168, 168,255};        // 把强调色改成青色
theme.FontSize = 16;                       // 字号小一点
theme.RadiusMd = 4;                     // 更小的圆角，更硬朗

方式二：从零构建主题

HX::HXTheme myTheme;
myTheme.WindowBackground = HXColor{30, 30, 35,255};
myTheme.PanelBackground = HXColor{42, 42, 48,255};
myTheme.WindowTitleBackground = HXColor{55, 55, 62,255};
myTheme.TextPrimary = HXColor{220, 220, 220,255};
myTheme.AccentPrimary = HXColor{255, 128, 0,255};      // 橙色主题！
myTheme.FontSize = 18;
myTheme.RadiusMd = 6;

HX::GetTheme() = myTheme;
HX::SetThemeMode(HX::HXThemeMode::ModernDark);  // 保留模式标记

💡 配色建议

• 背景层（Background）应该是最深的颜色
• 表面层（Surface）比背景亮 8~15%
• 边框（Border）用低对比度的灰色，不要太抢眼
• 强调色（Accent）饱和度适中即可，太鲜艳会刺眼

⚠️ 注意字段命名规范

HiEasyX 的主题字段有严格的命名约定，不要凭直觉猜：

• ✅ WindowTitleBackground（正确）
• ❌ WindowBorderColor（不存在，容易混淆）
• ✅ ButtonOnHoverBackground（正确）
• ❌ ButtonHoverBackground（不存在）

如果你发现改了一个字段但界面没变化，先检查拼写是否和 HXTheme 定义完全一致。

---

主题对各子系统的影响

主题不只是改改按钮颜色而已，HiEasyX 的几乎所有可视化子系统都会读取主题：

编辑器子系统（TextEditor）

HX::TextEditorProfile ep;
ep.FontSize = HX::GetTheme().FontSize;   // 跟随主题字号
HX::TextEditor(HXStr("editor"), lines, ep);

编辑器的背景色、光标色、选中高亮色、行号颜色，都会自动适配当前主题。如果你想让编辑器在暗色主题下使用不同的语法高亮方案，可以在创建 TextEditorProfile 时传入自定义的 Lexer 和颜色配置。

蓝图编辑器（Blueprint）

蓝图节点的视觉风格也受主题影响：

• 节点卡片背景取自 Surface
• 节点标题栏使用主题色的变体
• 网格线使用低透明度的 Border
• 选中节点的描边使用 Accent

ℹ️ 蓝图的特殊性

蓝图编辑器内部有自己的一套节点分类颜色（数学节点用琥珀色、逻辑节点用绿色等），这些颜色是语义性的，不会完全被主题覆盖。但整体的"卡片质感"、边框粗细、网格密度都会跟随主题。

表格与树形视图（Table / TreeView）

• 表头背景：Surface 的亮色变体
• 交替行底色：从 Background 和 Surface 自动计算
• 选中行：Accent + 透明度混合
• 悬停行：Accent 的极低透明度版本

DockSpace 与面板

• 分割条的悬停色使用 Accent
• Tab 标签的背景和文字颜色跟随 Surface / TextColor
• 拖拽时的半透明预览框使用 Accent + 半透明

---

动态主题切换示例

下面是一个完整的动态主题切换示例，你可以直接放到自己的项目里：

static bool isDark = true;

void DrawSettingsPanel() {
    HX::WindowProfile wp;
    if (HX::Window(HXStr("外观设置"), wp)) {
        HX::Text(HXStr("当前主题:"));

        HX::ButtonProfile btnDark, btnDim;
        if (HX::Button(HXStr("Modern Dark"), btnDark)) {
            HX::ApplyModernTheme(HX::HXThemeMode::ModernDark);
            isDark = true;
        }
        if (HX::Button(HXStr("Modern Dim"), btnDim)) {
            HX::ApplyModernTheme(HX::HXThemeMode::ModernDim);
            isDark = false;
        }

        HX::Text(HXStr(""));
        HX::Text(HXStr("自定义强调色:"));

        HX::SliderProfile1f sp;
        static float hue = 0.5f;
        if (HX::Slider1f(HXStr("色调"), hue, sp)) {
            // 把 hue [0,1] 转成 RGB 并写入主题
            HX::HXTheme& t = HX::GetTheme();
            t.Accent = HSLToRGB(hue * 360.0f, 0.8f, 0.6f);
        }
    }
}

💡 主题持久化

如果你想让用户的选择在下次打开程序时依然有效，可以把 HXThemeMode 和关键颜色值保存到配置文件（比如 INI 或 JSON），启动时读取并重新应用。

---

到这里，"快速开始"系列的内容就告一段落了。你已经了解了 HiEasyX 是什么、怎么安装、怎么写第一个程序、核心概念怎么用、以及怎么定制主题。

接下来，你可以：

• 浏览 API 参考 文档，深入了解每个控件的参数和用法
• 打开 example/ 目录下的示例程序，边看代码边运行
• 尝试自己组合 Window、Button、Slider、TextInput 做一个小工具

祝你编码愉快！如果有问题，欢迎随时查阅文档或翻看源码。HiEasyX 的代码风格很统一，读起来应该不会太困难。