```cpp
// 语义色角色(按“角色”取色,而不是按控件)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
Control, ControlHover, ControlPressed, ControlDisabled,
Accent, AccentHover, AccentPressed,
Border, Divider, FocusRing, Selection,
ScrollTrack, ScrollThumb, ScrollThumbHover,
Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
float cornerRadius; bool isDark; std::wstring name;
Color Get(ThemeRole) const; void Set(ThemeRole, Color);
static Theme Light(); static Theme Dark(); static Theme HighContrast(); };
// 应用级
void ThemeManager::SetAppTheme(const Theme&); void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme(); bool ThemeManager::IsDark();
// 跟随系统(注册表 AppsUseLightTheme + DWM AccentColor;WM_SETTINGCHANGE 等自动重解析)
void ThemeManager::SetFollowSystem(bool); bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark(); Color ThemeManager::SystemAccent(); Theme ThemeManager::SystemTheme();
// 测试钩子:模拟系统主题(绕过注册表)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// 色差重映射:任意硬编码色 → 主题色(精确表,未命中原样返回、保留 alpha)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>); Color ThemeManager::Map(Color);
// 钩子注册:返回 RAII HookHandle(析构自动断开);库内部固定钩子用 RegisterHookPermanent
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// 调试:主题名 + 各 Role 的 AARRGGBB(调试通道命令 23 GetTheme)
std::wstring ThemeManager::Dump();
// 窗口级
void Window::SetTheme(const Theme&); const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true); bool Window::IsUsingAppTheme(); void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged; // nullptr=应用级
ZSignal<Window*> UIZSignals::ThemeReapply; // 页面/标签切换后重套可见子树
```
- 取色优先级:**实例显式设色 > 窗口主题 > 应用主题**。控件只要被显式调用过任何 `Set*Color`,就标记为“用户设色”,主题切换**不再覆盖它**;其余控件跟随主题。
###block_red_start
**易错**
- `Backdrop` 是**窗口/背景基色**(浅色白、深色黑);`SetBackdrop/SetBackgroundColor` 显式指定 tint 后主题不再改它。
###block_red_end
- **`版本`**:`v1.19.0` 引入;窗口周边(标题栏三件套)跟随**系统**主题而非窗口主题;`WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE` 自动重解析。主题系统
Theme(v1.19.0+)
cpp
// 语义色角色(按“角色”取色,而不是按控件)
enum class ThemeRole { Text, TextSecondary, TextDisabled, TextOnAccent,
Surface, SurfaceAlt, SurfaceRaised, Backdrop, Overlay,
Control, ControlHover, ControlPressed, ControlDisabled,
Accent, AccentHover, AccentPressed,
Border, Divider, FocusRing, Selection,
ScrollTrack, ScrollThumb, ScrollThumbHover,
Danger, Warning, Success, Info, Shadow, Count };
struct Theme { Color colors[(int)ThemeRole::Count]; FontSpec font, fontCaption, fontMono;
float cornerRadius; bool isDark; std::wstring name;
Color Get(ThemeRole) const; void Set(ThemeRole, Color);
static Theme Light(); static Theme Dark(); static Theme HighContrast(); };
// 应用级
void ThemeManager::SetAppTheme(const Theme&); void ThemeManager::SetLight/DarkAppTheme();
Theme& ThemeManager::AppTheme(); bool ThemeManager::IsDark();
// 跟随系统(注册表 AppsUseLightTheme + DWM AccentColor;WM_SETTINGCHANGE 等自动重解析)
void ThemeManager::SetFollowSystem(bool); bool ThemeManager::IsFollowingSystem();
bool ThemeManager::SystemPrefersDark(); Color ThemeManager::SystemAccent(); Theme ThemeManager::SystemTheme();
// 测试钩子:模拟系统主题(绕过注册表)
void ThemeManager::DebugForceSystemTheme(bool enable, bool dark, bool highContrast);
// 色差重映射:任意硬编码色 → 主题色(精确表,未命中原样返回、保留 alpha)
void ThemeManager::SetColorMap(std::unordered_map<uint32_t, Color>); Color ThemeManager::Map(Color);
// 钩子注册:返回 RAII HookHandle(析构自动断开);库内部固定钩子用 RegisterHookPermanent
HookHandle ThemeManager::RegisterHook(std::function<void(const Theme&)>);
HookHandle ThemeManager::RegisterSubtreeApplier(std::function<void(UIElement*, const Theme&)>);
// 调试:主题名 + 各 Role 的 AARRGGBB(调试通道命令 23 GetTheme)
std::wstring ThemeManager::Dump();
// 窗口级
void Window::SetTheme(const Theme&); const Theme& Window::GetTheme();
void Window::SetUseAppTheme(bool = true); bool Window::IsUsingAppTheme(); void Window::RefreshTheme();
ZSignal<Window*> UIZSignals::ThemeChanged; // nullptr=应用级
ZSignal<Window*> UIZSignals::ThemeReapply; // 页面/标签切换后重套可见子树
- 取色优先级:实例显式设色 > 窗口主题 > 应用主题。控件只要被显式调用过任何
Set*Color,就标记为“用户设色”,主题切换不再覆盖它;其余控件跟随主题。
易错
Backdrop是窗口/背景基色(浅色白、深色黑);SetBackdrop/SetBackgroundColor显式指定 tint 后主题不再改它。
版本:v1.19.0引入;窗口周边(标题栏三件套)跟随系统主题而非窗口主题;WM_SETTINGCHANGE/WM_THEMECHANGED/WM_DWMCOLORIZATIONCOLORCHANGED/WM_SYSCOLORCHANGE自动重解析。