chinboy
3.3 KiB
AtomUI.Controls 模块概览
AtomUI.Controls 是公共控件和通用 Primitives 模块。它依赖 AtomUI.Core、AtomUI.Controls.Shared、AtomUI.Fonts.AlibabaSans、AtomUI.Icons.AntDesign 和 AtomUI.Generator。
职责
- 提供桌面控件包复用的基础控件、抽象控件和 Primitives。
- 承载至少被两个产品终端真实复用的平台无关抽象 Control Token 定义；抽象定义层无 identity，
Desktop/Mobile 产品包分别拥有
sealed终端 Token。 - 提供公共主题 Provider：
CommonControlThemesProvider与BrowserCommonControlThemesProvider。 - 注册公共控件 Token、本地化 Catalog 和内置 Translation Bundle。
- 提供 Icon、ItemsControl、ScrollViewer、Form、Watermark、QRCode、Badge 抽象等公共能力。
注册入口
入口位于 src/AtomUI.Controls/ThemeManagerBuildExtensions.cs：
builder.UseCommonControls();
该方法会：
- 注册源生成器生成的公共控件 Token 类型。
- 根据
RuntimePlatform.Features.SupportsNativeWindow选择桌面或浏览器公共主题 Provider。 - 通过生成式模块注册把公共 Catalog 和内置翻译加入
builder.Localization。
UseDesktopControls() 会先调用 UseCommonControls()，所以普通桌面应用无需单独调用本方法。
图片加载职责
AtomUI.Controls 拥有：
AsyncImage通用异步显示控件及 Theme。ImageLoadController，统一AsyncImage与 Avatar 的 generation、取消、fallback、progress、状态提交和结果租约。- Avatar 的
Source/FallbackSource/RequestOptions统一 API，并删除Src、BitmapSrc和 proposedBitmapUrl。 - 统一
SvgImageCodec、Avalonia SVG owned wrapper，以及在UseCommonControls()中对该 codec 和 Shared image service 的显式注册。
Controls 不拥有 HTTP、memory/file cache、全局 scheduler 或第二个 loader。UseCommonControls() 幂等地补齐
Shared 默认图片注册并添加本包 SVG codec；UseDesktopControls() 继续通过 Common 得到同一个 application-scoped loader。
codec 只消费 Shared 已按当前安全策略验证的不可变 SVG 字节，始终使用 stream overload，不自行打开 URL/File；SvgImage 创建、
Source/Size 访问和释放遵守 UI dispatcher ownership。
准确 API 和生命周期只在 统一图片加载系统及其
控件 API中定义；底层类型见
公共契约。
关键目录
| 目录 | 说明 |
|---|---|
Primitives/ |
桌面控件复用的基础装饰、动效、视觉层 |
Icon/ |
图标控件与图标主题 |
ItemsControl/ |
ItemsControl 相关反射扩展和主题 |
Form/ |
表单验证基础能力 |
Grid/、FlexPanel/ |
布局基础 |
Badge/、Buttons/、Select/ |
多个桌面控件复用的抽象层 |
具体桌面控件文档应放在 ../../controls/desktop/overview.md，本模块文档只解释公共基础层。 Control Token 定义层的提取门槛、Generator 扁平化和运行时隔离见 Control Design Token 继承架构。该能力不表示仓库已经存在 Mobile 终端或共享 Token 基类。