AtomUI 主题系统揭秘一行代码切换暗黑模式Token 驱动的换肤终极指南【免费下载链接】AtomUIAn enhancement and extension library for Avalonia, bringing the Ant Design design language, modern controls, theming, native integrations, and cross-platform UI capabilities to .NET desktop apps.项目地址: https://gitcode.com/gh_mirrors/at/AtomUIAtomUI是面向 Avalonia 的增强库为 .NET 桌面应用带来 Ant Design 设计语言、现代化控件与跨平台 UI 能力。它的主题系统最亮眼的两点 一行代码即可切换暗黑模式以及通过Design Token设计令牌驱动的一键换肤——改一个主色整个应用的颜色体系自动重算全程原子化、无闪烁。本文带你快速搞懂它的设计思路和上手方法。一、为什么 AtomUI 的主题系统不太一样传统做法是把颜色堆在ResourceDictionary里手动覆盖问题多多派生颜色靠人肉维护、切换时容易读到一半新一半旧的值、NativeAOT 下反射扫描不可靠。AtomUI 采用了一个非常清爽的心智模型主题配置是源代码ThemeCompiler 是编译器ThemeSnapshot 是不可变编译产物。ThemeDefinition / ThemeConfig ← 你写的主题配置 ↓ 绑定 规范化 ThemeCompiler ← 派生算法Default / Dark / Compact ↓ 编译 Immutable ThemeSnapshot ← 冻结的完整主题结果 ↓ 原子发布 ResourceProvider → ControlTheme → 控件这套模型直接带来三大好处特性说明⚡ 原子切换先编译完整新快照再一次性交换引用UI 永远不会看到中间状态 单一真源你只改少量 Seed Token暗色/派生/别名颜色全部由算法计算️ AOT 友好Token 描述符、资源 key 全部在构建期由 Source Generator 生成运行时零反射二、暗黑模式一行代码搞定 AtomUI 把外观Appearance抽象为枚举Light/Dark暗黑并不是一套手写死的深色资源表而是一条派生算法链// 追加 Dark 算法暗色整套颜色体系自动派生 var config new ThemeConfigBuilder() .WithAlgorithms(ThemeAlgorithm.Default, ThemeAlgorithm.Compact, ThemeAlgorithm.Dark) .Build();运行时切换主题只需一次调用await themeManager.ApplyThemeAsync( new ThemeRequest(DaybreakBlue, config, ThemeTransitionReason.UserRequest));几个实用细节跟随系统ThemeManager会订阅系统外观变化ThemeTransitionReason.FollowSystem触发自动切换紧凑模式追加ThemeAlgorithm.Compact即可算法顺序本身就是主题语义内置主题默认主题为DaybreakBlue可用AvailableThemes查看全部主题ReloadThemesAsync()手动刷新用户主题目录。官方 Gallery 的深色开关就是这么做的——GalleryWorkspaceViewModel.cs 中一个ToggleDarkModeCommand内部只是在算法链上追加/移除Dark后提交新ThemeRequest。三、Token 驱动换肤改一处全局生效 ✨AtomUI 的 Token 分两层理解了这两层换肤就再无神秘感Global Token全局设计语言主色ColorPrimary、文字颜色、圆角、控件高度、字号、动效时长……改它等于改整个应用的设计语言。Control Own Token控件私有语义只属于某个控件的稳定设计值例如Rating.StarGap、DatePicker.CellHeight。Global Token ──(按控件覆盖)── Effective Global Token Control Own Token Effective Control Token ── ControlTheme 渲染这意味着你可以做到只把 Button 的主色变成绿色其他控件仍是蓝色——这是 Button 维度的全局 Token 差量不会污染全局也不会波及 DatePicker。换肤速查表你的需求正确入口换整个应用的主色/圆角/字体Global Token只改所有 Button 的主色Button 下的 Global Token 覆盖改 Button 独有的内容内边距Button Own Token某个页面局部用暗色ThemeConfigProvider局部主题换模板结构/状态映射自定义 ControlTheme四、三种姿势定制你自己的主题1️⃣ 代码里改 Token最快启动时通过 Builder 设定初始主题运行时用ApplyThemeAsync换所有输入都走同一条 schema配置错名字会在编译期就报错。2️⃣ 主题定义 XML可分发的主题包一份.theme.xml就能声明一个可命名、可切换的完整主题全局 Token、控件级覆盖、算法链一次写清。用户把主题文件放进应用主题目录应用调用ReloadThemesAsync()原子提交整个目录——要么全成功要么维持原样绝不出现半新半旧。3️⃣ 局部主题一半暗色、一半亮色ThemeConfigProvider可以给某棵 UI 子树建立独立的 ThemeContext——比如代码编辑器页面用暗色其余区域保持亮色Popup 还会正确继承所属子树的主题互不干扰。五、切换为什么不会闪一半一次主题更新被拆成五个阶段Capture → Prepare → Commit → Publish → Complete。编译失败或配置非法时Commit 不会发生旧主题完整保留成功后所有 UI 一次性指向新快照。这就是你看到切换平滑无闪烁的根本原因。六、上手路线 主题定制指南docs/guides/theming/customization.md本文所有结论的权威来源主题架构详解docs/architecture/systems/theming/runtime.md、docs/architecture/systems/theming/overview.md主题 XML 规范docs/reference/theming/theme-definition-xml-v1.md核心运行时源码src/AtomUI.Core/Theme/ThemeManager.cs、IThemeManager.cs效果演示controlgallery/AtomUIGallery/Gallery 里可以实时切换主题、暗黑与紧凑模式记住五句话就够了Global Token 定义设计语言Own Token 只表达控件私有语义控件可以覆盖全局 Token但影响不到其他控件主题 配置 → 编译 → 不可变快照 → 原子发布暗黑/紧凑是算法链不是资源开关局部主题靠ThemeConfigProvider全局换肤靠ApplyThemeAsync。下一篇文章见【免费下载链接】AtomUIAn enhancement and extension library for Avalonia, bringing the Ant Design design language, modern controls, theming, native integrations, and cross-platform UI capabilities to .NET desktop apps.项目地址: https://gitcode.com/gh_mirrors/at/AtomUI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考