---
title: "Theme"
description: "主题配色与样式管理。"
---

---
title: Theme
description: 主题配色与样式管理。
---

`include/XBase/Theme.h` · `XBase::Theme`

Theme 模块通过 XBase 自有值类型管理配色与字体。ImGui 类型和字体指针只存在于 XBase 私有实现。

## 初始化与预设

```cpp
void Init();
void Shutdown();
void ApplyPreset(Preset preset);
void ApplyStyle(const Style& style);
void ConfigureInteraction(bool keyboardNavigation, bool mouseEnabled);
```

- `Init()` — 应用 Dark 预设；`Shutdown()` 释放字体缓存与 Context 绑定。
- `Preset` 枚举：`Dark`、`Light`、`ClassicBlue`、`Custom`。
- `ApplyPreset(Preset::Custom)` 会重新应用最近一次 `ApplyCustom()` 保存的 `ColorSet`。
- `ApplyStyle()` 接收完整的 `Style` 结构体（文本/背景/按钮/边框/圆角/内边距等），一次应用全部字段；`ChildRounding`、`PopupRounding`、`ScrollbarRounding`、`GrabRounding` 复用 `frameRounding`，不会更新 `Custom` 预设保存的 `ColorSet`。
- `ConfigureInteraction()` 控制键盘导航与鼠标输入：`keyboardNavigation=false` 时关闭 ImGui 导航，`mouseEnabled=false` 时屏蔽鼠标。

## 自定义配色

```cpp
struct ColorSet {
    ColorF primary;       // 主色（勾选、滑块）
    ColorF accent;        // 强调色（按钮激活）
    ColorF background;    // 窗口背景
    ColorF surface;       // 控件背景
    ColorF text;          // 文字
    ColorF textDisabled;  // 禁用文字
    ColorF border;        // 边框
    ColorF highlight;     // 高亮
};

void ApplyCustom(const ColorSet& colors);
ColorSet GetColors();
```

## 字体

```cpp
FontId LoadFont(const char* path, float size);
bool SetDefaultFont(FontId font);
```

- `LoadFont` — 从 TTF 文件加载字体；成功返回不透明 `FontId`，失败返回无效 ID
- `SetDefaultFont` — 按 ID 选择默认字体；XBase 在内部验证 ID，不向宿主暴露 `ImFont*`

## 预设持久化

```cpp
void SavePreset(const std::string& name);
bool LoadPreset(const std::string& name);
```

- `SavePreset` — 将当前 `ColorSet` 保存到 `Config` 系统，调用 `Config::Save()` 持久化到磁盘
- `LoadPreset` — 从 `Config` 加载指定名称的主题并应用；如不存在返回 `false`

保存的键格式为 `theme.<name>.*`，例如 `theme.myBlue.primary.r`。