AtomUI/docs/Core/ThemeSystem/Overview.md

AtomUI 主题系统架构文档 — 总览

本文档描述 AtomUI 主题系统的整体设计架构。AtomUI 主题系统是对 Ant Design 5.0 Design Token 体系 的 C# / Avalonia 完整移植，实现了与 Ant Design TypeScript 版本功能等价的主题定制能力。

---

1. 设计背景与目标

1.1 Ant Design 5.0 主题定制体系回顾

Ant Design 5.0 采用了 Design Token 驱动的主题系统，核心理念是：

• Seed Token（种子变量）：极少数用户可直接修改的基础设计意图（如品牌主色 colorPrimary、字体大小 fontSize），修改后自动级联派生下层所有 Token。
• Map Token（梯度变量）：由 Seed Token 通过 主题算法（Algorithm） 自动派生，形成完整的色彩梯度、尺寸梯度、字体梯度等。
• Alias Token（别名变量）：对 Map Token 的语义化封装，面向组件批量消费（如 colorTextDisabled、colorBgContainer）。
• Component Token（组件变量）：每个组件独有的 Token，可以从全局 SharedToken 派生，也可以被用户单独覆盖。
• 主题算法：Default（亮色）、Dark（暗色）、Compact（紧凑），算法可自由组合。

Ant Design 在 React 中通过 ConfigProvider 的 theme 属性实现上述能力。AtomUI 在 .NET / Avalonia 平台完整还原了这一设计。

1.2 AtomUI 的对应实现

Ant Design (TypeScript)	AtomUI (C#)
theme.token (Seed/Map/Alias)	DesignToken (partial class, 三层 Token 定义)
theme.algorithm	ThemeAlgorithm enum + IThemeVariantCalculator
theme.components[Component].token	AbstractControlDesignToken 子类
ConfigProvider	ThemeConfigProvider (XAML 组件) + XML 主题定义
@ant-design/colors (色板生成)	PaletteGenerator (HSV 色板算法)
CSS-in-JS Token 注入	Avalonia ResourceDictionary + Token MarkupExtension

1.3 设计目标

1. 完全还原 Ant Design 5.0 Design Token 语义 — 从 Seed → Map → Alias → Component 四层推导链完整实现。
2. 主题算法可组合 — Default / Dark / Compact 可任意叠加（装饰器模式）。
3. 运行时主题热切换 — 利用 Avalonia ThemeVariant + ResourceDictionary.ThemeDictionaries 实现零重启切换。
4. XML + XAML 双通道配置 — 全局主题通过 XML 定义文件配置，局部嵌套通过 XAML ThemeConfigProvider 配置。
5. 源代码生成器驱动 — Token ResourceKey 枚举通过 Roslyn Source Generator 自动生成，编译期保障类型安全。
6. 组件级 Token 隔离 — 每个组件有独立的 Token 作用域，支持组件级别的 SharedToken 覆盖。

---

2. 整体架构

2.1 系统层次图

┌──────────────────────────────────────────────────────────────────┐
│                        Application Layer                         │
│                                                                  │
│  app.UseAtomUI(builder => {                                      │
│      builder.UseDesktopControls();                               │
│      builder.WithDefaultTheme("DaybreakBlue");                   │
│  });                                                             │
└────────────────────────────┬─────────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────────┐
│                    ThemeManagerBuilder                            │
│  收集: ControlDesignTokens, ControlThemesProviders,              │
│        LanguageProviders, ThemeAssetPathProviders                 │
│  Build() ──────────────────▼─────────────────────────            │
│                        ThemeManager                               │
│  (extends Avalonia.Styling.Styles, implements IThemeManager)      │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │ ThemePool: Dict<ThemeVariant, Theme>                     │     │
│  │                                                         │     │
│  │  ┌──────────────┐ ┌───────────────────┐ ┌────────────┐ │     │
│  │  │ DaybreakBlue │ │ DaybreakBlue-Dark │ │ ...        │ │     │
│  │  │ (Theme)      │ │ (Theme)           │ │            │ │     │
│  │  └──────┬───────┘ └────────┬──────────┘ └────────────┘ │     │
│  │         │                  │                            │     │
│  │         ▼                  ▼                            │     │
│  │  ┌───────────────────────────────┐                      │     │
│  │  │      Theme.BuildThemeResource()                      │     │
│  │  │  1. Load Seed Token config                           │     │
│  │  │  2. Calculator.Calculate() → Map Tokens              │     │
│  │  │  3. CalculateAliasTokenValues() → Alias Tokens       │     │
│  │  │  4. ControlToken.CalculateTokenValues()              │     │
│  │  │  5. BuildResourceDictionary() → ResourceDictionary   │     │
│  │  └───────────────────────────────┘                      │     │
│  └─────────────────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────────┐
│                    Avalonia Resource System                       │
│                                                                  │
│  ThemeManager.Resources.ThemeDictionaries[themeVariant]           │
│    = Theme.ThemeResource (ResourceDictionary)                    │
│                                                                  │
│  控件通过 DynamicResource / MarkupExtension 消费 Token:          │
│    {atom:SharedTokenResource ColorPrimary}                       │
│    {atom:TokenResource ButtonPrimaryColor}                       │
└──────────────────────────────────────────────────────────────────┘

2.2 核心模块划分

模块	目录	职责
主题管理	Theme/ 根目录	ThemeManager, Theme, ThemeDefinition, Builder 模式
Token 体系	Theme/TokenSystem/	DesignToken, AbstractControlDesignToken, Token 属性/Attribute
Token 定义	Theme/TokenSystem/TokenDefinitions/	DesignToken partial class 的 Seed/Map/Alias 定义
主题算法	Theme/Styling/	IThemeVariantCalculator 及 Default/Dark/Compact 实现
调色板	Theme/Palette/	PaletteGenerator, PresetPrimaryColor, PresetPalettes
资源扩展	Theme/ (TokenResourceExtension 等)	XAML MarkupExtension, StyleExtensions
Source Generator	AtomUI.Generator/ (外部项目)	TokenResourceKeyGenerator 自动生成 Enum 资源键

2.3 与 Ant Design TypeScript 版本的对应关系

Ant Design (TypeScript)                    AtomUI (C#)
──────────────────────────                 ──────────────────────────────────
theme/interface/seeds.ts                   DesignToken.Seed.cs
theme/interface/maps/colors.ts             DesignToken.ColorPrimaryMap.cs 等
theme/interface/maps/font.ts               DesignToken.FontMap.cs
theme/interface/maps/size.ts               DesignToken.SizeMap.cs
theme/interface/maps/style.ts              DesignToken.StyleMap.cs
theme/interface/alias.ts                   DesignToken.Alias.cs
theme/themes/default/index.ts              DefaultThemeVariantCalculator.cs
theme/themes/dark/index.ts                 DarkThemeVariantCalculator.cs
theme/themes/compact/index.ts              CompactThemeVariantCalculator.cs
@ant-design/colors                         PaletteGenerator.cs
theme/util/genComponentStyleHook.ts        AbstractControlDesignToken.cs
ConfigProvider (theme prop)                ThemeConfigProvider.cs + XML 定义
CSS-in-JS token injection                  ResourceDictionary + MarkupExtension

---

3. 文档索引

本主题系统文档拆分为以下模块文档：

文档	描述
Overview.md	本文件 — 总览
TokenArchitecture.md	Design Token 四层架构详解（Seed → Map → Alias → Component）
ThemeAlgorithm.md	主题算法（Default/Dark/Compact）与调色板生成
ThemeManagement.md	主题管理器、主题生命周期、运行时切换
TokenResourceBinding.md	Token 资源绑定、XAML MarkupExtension、Source Generator
ThemeCustomizationPrinciples.md	主题自定义原理说明（加载机制、作用域实现、组件级覆盖）
ThemeCustomizationGuide.md	主题定制开发者指南（完整步骤、API 参考、Gallery 示例解读）

---

4. 快速参考：源文件清单

Theme/ 根目录

文件	职责
ITheme.cs	主题公共接口
Theme.cs	主题实现（加载、构建资源、生命周期）
IThemeManager.cs	主题管理器公共接口
ThemeManager.cs	主题管理器实现（主题池、切换、语言、动效开关）
IThemeManagerBuilder.cs	构建器接口
ThemeManagerBuilder.cs	构建器实现
ThemeAlgorithm.cs	主题算法枚举（Default, Dark, Compact）
ThemeDefinition.cs	主题定义数据模型
ThemeDefinitionReader.cs	XML 主题定义文件解析器
ThemeConfigProvider.cs	XAML 局部主题配置组件
IThemeConfigProvider.cs	局部主题配置接口
BaseControlTheme.cs	控件主题基类
IControlThemesProvider.cs	控件主题提供者接口
IThemeAssetPathProvider.cs	主题资产路径提供者接口
ControlTokenResourcesHost.cs	控件级 Token 资源作用域宿主
IControlTokenResourceScopeProvider.cs	控件级 Token 作用域提供者接口
TokenResourceExtension.cs	泛型 Token 资源 XAML 标记扩展基类
TokenSetter.cs	Token 设置器（用于 XAML 配置）
ControlTokenInfoSetter.cs	控件 Token 信息设置器
ThemeExceptions.cs	主题系统异常定义

Theme/TokenSystem/

文件	职责
IDesignToken.cs	Design Token 接口
AbstractDesignToken.cs	Design Token 抽象基类（配置加载、资源构建、Clone）
IControlDesignToken.cs	控件 Design Token 接口
AbstractControlDesignToken.cs	控件 Design Token 抽象基类（组件级 Token）
DesignTokenKind.cs	Token 分类枚举（Seed, Map, Alias）
DesignTokenKindAttribute.cs	Token 分类标注 Attribute
GlobalDesignTokenAttribute.cs	全局 Token 标注 Attribute
ControlDesignTokenAttribute.cs	控件 Token 标注 Attribute
NotTokenDefinitionAttribute.cs	非 Token 属性排除标注
ControlTokenConfigInfo.cs	控件 Token 配置信息
ITokenValueConverter.cs	Token 值转换器接口
TokenValueConverterAttribute.cs	Token 值转换器标注
BuiltInTokenValueConverters.cs	内置 Token 值转换器集合

Theme/TokenSystem/TokenDefinitions/

文件	内容	Token 层级
DesignToken.cs	DesignToken 主类（构造、初始化、Alias 计算）	—
DesignToken.Seed.cs	Seed Token 定义	Seed
DesignToken.ColorPrimaryMap.cs	主色系梯度（1-10号色）	Map
DesignToken.ColorSuccessMap.cs	成功色系梯度	Map
DesignToken.ColorWarningMap.cs	警戒色系梯度	Map
DesignToken.ColorErrorMap.cs	错误色系梯度	Map
DesignToken.ColorInfoMap.cs	信息色系梯度	Map
DesignToken.ColorLinkMap.cs	链接色系梯度	Map
DesignToken.ColorNeutralMap.cs	中性色系（文本/边框/填充/背景）	Map
DesignToken.ColorMap.cs	通用颜色（黑/白/遮罩/选区）	Map
DesignToken.FontMap.cs	字体梯度（大小/行高）	Map
DesignToken.SizeMap.cs	尺寸梯度（XXS-XXL）	Map
DesignToken.HeightMap.cs	控件高度梯度	Map
DesignToken.StyleMap.cs	样式梯度（圆角/线宽/动效时长）	Map
DesignToken.Alias.cs	别名 Token（语义化消费层）	Alias

Theme/Styling/

文件	职责
IThemeVariantCalculator.cs	主题变体计算器接口
AbstractThemeVariantCalculator.cs	计算器抽象基类（装饰器模式）
DefaultThemeVariantCalculator.cs	默认（亮色）算法
DarkThemeVariantCalculator.cs	暗色算法
CompactThemeVariantCalculator.cs	紧凑算法
IThemeVariantCalculatorFactory.cs	自定义计算器工厂接口
CalculatorUtils.cs	计算工具（字体/尺寸/圆角/动效时长派生）
ColorMap.cs	10 级色阶映射
SharedTokenResourceExtension.cs	全局 Token XAML 标记扩展
IControlThemeProvider.cs	控件主题提供者接口
ControlThemeProviderAttribute.cs	控件主题提供者标注
SetterValueFactory.cs	Setter 值工厂
StyleExtensions.cs	Style 扩展方法

Theme/Palette/

文件	职责
PaletteGenerator.cs	色板生成器（HSV 算法，对标 @ant-design/colors）
PresetPrimaryColor.cs	14 种预设主色
PresetPalettes.cs	预计算的亮色/暗色调色板集合