AtomUI/docs/Core/Font/Overview.md

AtomUI 字体系统 — 总览

本文档描述 AtomUI 字体系统的整体设计架构。AtomUI 字体系统建立在 Avalonia 的 EmbeddedFontCollection 和 FontManager 基础之上，结合 AtomUI 的 Design Token 主题系统，实现了从字体包嵌入、字体族注册、Token 驱动的字体大小/行高派生，到运行时全局字体切换的完整能力。

---

1. 设计背景与目标

1.1 Ant Design 5.0 排版规范

Ant Design 5.0 在排版（Typography）方面有如下设计要求：

• 字体族（Font Family）：优先使用系统默认界面字体，同时提供备用字体库，在不同平台保持良好的易读性和可读性。
• 字体大小（Font Size）：以 14px 为基准字号，通过数学公式自动派生出从小号到一级标题的完整字号梯度。
• 行高（Line Height）：与字号配套，遵循 (fontSize + 8) / fontSize 的计算公式自动派生。
• 字重（Font Weight）：标题类组件使用 SemiBold，正文使用 Normal。

AtomUI 在 .NET / Avalonia 平台完整还原了这一排版设计。

1.2 AtomUI 字体系统的三大集成点

┌───────────────────────┐     ┌─────────────────────────┐     ┌──────────────────────┐
│   字体包（Font Package）│     │ Design Token 主题系统     │     │  AXAML 资源绑定        │
│                       │     │                         │     │                      │
│  EmbeddedFontCollection│────►│  Seed Token: FontFamily │────►│ {atom:SharedToken-   │
│  字体文件嵌入 (.ttf)    │     │  Map Token: FontSize*   │     │  Resource FontFamily}│
│  自定义 URI Scheme     │     │  Alias Token: FontSize- │     │ {atom:SharedToken-   │
│  (fonts:AlibabaSans)   │     │  Icon, FontWeightStrong │     │  Resource FontSize}  │
│                       │     │  算法派生字号/行高梯度     │     │                      │
└───────────────────────┘     └─────────────────────────┘     └──────────────────────┘

1. 字体包（Font Package） — 将字体文件（.ttf/.otf）嵌入为 Avalonia 资源，通过 EmbeddedFontCollection 注册到 FontManager，使字体在应用中全局可用。
2. Design Token 主题系统 — 字体族作为 Seed Token (FontFamily) 参与主题推导链，字号和行高通过主题算法自动派生为 Map Token 梯度。
3. AXAML 资源绑定 — 控件主题通过 {atom:SharedTokenResource FontFamily} 等标记扩展消费字体 Token，实现字体与主题的动态绑定。

1.3 设计目标

1. 开箱即用 — 内置 Alibaba Sans 字体包，一行代码即可启用，无需依赖系统字体。
2. Token 驱动 — 字号、行高、字重等排版属性全部由 Design Token 系统管理，修改 Seed Token 即可全局级联。
3. 可扩展 — 开发者可以制作自己的字体包，替换默认字体或添加额外字体。
4. 运行时可切换 — 通过修改 Token 资源字典中的 FontFamily 值即可运行时切换全局字体。
5. 跨平台一致性 — 字体包嵌入机制确保在 Windows/macOS/Linux（未来还有 iOS/Android）上字体显示一致。

---

2. 系统架构

2.1 组件关系图

┌──────────────────────────────────────────────────────────────────────────┐
│  应用层（Application Layer）                                               │
│                                                                          │
│  app.UseAtomUI(builder => {                                              │
│      builder.UseAlibabaSansFont();      // 注册字体包                      │
│      builder.UseDesktopControls();                                       │
│      builder.WithDefaultFontFamily(...) // 可选：覆盖默认字体              │
│  });                                                                     │
└─────────────────────────┬──────────────────────────────────┬─────────────┘
                          │                                  │
┌─────────────────────────▼────────────────┐  ┌──────────────▼─────────────┐
│  AtomUI.Fonts.AlibabaSans                │  │  AtomUI.Core 主题系统        │
│  ┌─────────────────────────────────────┐ │  │  ┌──────────────────────┐   │
│  │ AlibabaSansFontCollection           │ │  │  │ DesignToken          │   │
│  │   : EmbeddedFontCollection          │ │  │  │  .FontFamily (Seed)  │   │
│  │   fonts:AlibabaSans → avares://     │ │  │  │  .FontSize   (Seed)  │   │
│  │   AtomUI.Fonts.AlibabaSans/Assets   │ │  │  │  .FontSizeSM (Map)   │   │
│  │                                     │─┼──►  │  .FontSizeLG (Map)   │   │
│  │ ThemeManagerBuilderExtensions       │ │  │  │  ...更多 Map/Alias    │   │
│  │   .UseAlibabaSansFont()             │ │  │  └──────────┬───────────┘   │
│  │                                     │ │  │             │               │
│  │ AppBuilderExtension                 │ │  │  CalculatorUtils            │
│  │   .WithAlibabaSansFont()            │ │  │   .CalculateFontMap-       │
│  └─────────────────────────────────────┘ │  │    TokenValues()            │
└──────────────────────────────────────────┘  └─────────────────────────────┘
                                                            │
                                              ┌─────────────▼─────────────┐
                                              │  控件主题（Control Themes） │
                                              │                           │
                                              │  WindowTheme.axaml:       │
                                              │    FontFamily="{atom:     │
                                              │    SharedTokenResource    │
                                              │    FontFamily}"           │
                                              │                           │
                                              │  PopupRootTheme.axaml:    │
                                              │    FontFamily="{atom:     │
                                              │    SharedTokenResource    │
                                              │    FontFamily}"           │
                                              └───────────────────────────┘

2.2 核心模块划分

模块	项目	职责
字体包	AtomUI.Fonts.AlibabaSans	内置 Alibaba Sans 字体嵌入、FontManager 注册
字体 Token	AtomUI.Core (Theme/TokenSystem/)	Seed Token FontFamily/FontSize，Map Token 字号/行高梯度派生
字体梯度算法	AtomUI.Core (Theme/Styling/CalculatorUtils.cs)	从基准字号自动派生完整字号/行高序列
字体工具	AtomUI.Core (Media/FontUtils.cs, TextUtils.cs)	em 转 px 工具、文本尺寸测量工具
控件字体绑定	AtomUI.Desktop.Controls (Themes/*.axaml)	通过 Token 标记扩展在控件主题中消费字体 Token

---

3. 文档索引

本字体系统文档拆分为以下子文档：

文档	描述
Overview.md	本文件 — 总览
FontPackageDesign.md	字体包内部设计原理（以 AtomUI.Fonts.AlibabaSans 为例）
FontTokenIntegration.md	字体与 Design Token 系统的集成（Seed → Map → Alias 字体推导链）
UsingBuiltInFont.md	开发者指南：在应用中使用 AtomUI 内置字体
CreatingCustomFontPackage.md	开发者指南：制作自定义字体包
RuntimeFontSwitching.md	运行时字体切换机制与实践

---

4. 源文件清单

AtomUI.Fonts.AlibabaSans

文件	职责
AlibabaSansFontCollection.cs	字体集合定义，继承 EmbeddedFontCollection
AppBuilderExtension.cs	Avalonia AppBuilder 扩展方法（纯 Avalonia 场景）
ThemeManagerBuilderExtensions.cs	AtomUI IThemeManagerBuilder 扩展方法（AtomUI 主题场景）
Properties/AssemblyInfo.cs	XAML 命名空间定义 (XmlnsDefinition)
AtomUI.Fonts.AlibabaSans.csproj	项目文件，配置 AvaloniaResource 嵌入字体文件
Assets/*.ttf	6 个字重的 Alibaba Sans 字体文件

AtomUI.Core（字体相关）

文件	职责
Theme/TokenSystem/TokenDefinitions/DesignToken.Seed.cs	Seed Token：FontFamily、FontSize
Theme/TokenSystem/TokenDefinitions/DesignToken.FontMap.cs	Map Token：字号梯度、行高梯度、文字高度
Theme/TokenSystem/TokenDefinitions/DesignToken.Alias.cs	Alias Token：FontSizeIcon、FontWeightStrong
Theme/TokenSystem/TokenDefinitions/DesignToken.cs	Alias 计算逻辑（CalculateAliasTokenValues）
Theme/Styling/CalculatorUtils.cs	字体梯度派生算法（CalculateFontMapTokenValues、CalculateFontSize）
Theme/ThemeManagerBuilder.cs	WithDefaultFontFamily() API
ApplicationExtensions.cs	UseAtomUI() 中的字体覆盖逻辑
Media/FontUtils.cs	em 到 px 转换工具
Media/TextUtils.cs	文本尺寸计算工具