mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-22 00:46:48 +08:00
chinboy
a6fc404ba6
新增 `docs/guides/typography/`，补上字体包的操作路径。此前 `architecture/systems/typography/` 只描述字体子系统的架构与契约，要新做一个包得自己去读 `AtomUI.Fonts.AlibabaSans` 和 `AtomUI.Fonts.AlibabaPuHuiTi` 的源码反推步骤。按文档分类规范，"怎么完成任务"属于 Guide。 教程从"注册和生效是两件事"开篇，而非从建项目开始。注册链路与生效链路互不相干，只在 Avalonia 解析 `FontFamily` 字符串时汇合，因此只注册 `FontCollection` 不会改变任何界面外观 —— 这是做字体 包最费时间的坑，放在写代码之前说。其余章节依次为建项目、确认字族名、`FontCollection`、两个注册 扩展、`WithDefaultFontFamily` 激活、验证排查、分发许可与交付清单。 两处内容经实测修正，未照现有两个包的表象推断： - `fc-scan` 输出为一行逗号分隔，且只有第一项可用。实扫 PuHuiTi 得 `Alibaba PuHuiTi 3.0,阿里巴巴普惠体 3.0,Alibaba PuHuiTi 3.0 55 Regular,...`，本地化名与子族 全名写进代码均不生效。同一命令解释了字重归组：AlibabaSans 六个面首项均为 `Alibaba Sans`。 文中给出真实输出而非文字描述。 - `FontManager.Current.SystemFonts` 全仓库无调用点，该排查片段已对 Avalonia 12.1.1 单独编译 验证后收录。 记录三处读现有包看不出的行为，均经源码核对： - 主题配置显式声明 `FontFamily` Token 时 `WithDefaultFontFamily` 完全失效。 `ThemeManager.AddDefaultFont` 在该 key 已存在时提前返回，是有意的优先级设计，但表现为"调用已 执行而界面未变"，故列入排查清单。 - 字符串格式错误抛异常，字族缺失只静默回退，两种失败模式的可观测性不同。 - `AtomUI.Controls` 引用 `AtomUI.Fonts.AlibabaSans` 但不调用 `AddFontCollection`。引用只保证资源 随构建产出，注册是应用的责任，库不应代应用决定。 `AlibabaSans` 的注册扩展位于全局命名空间，按历史遗留记录而非范例，并指出可观察后果：Desktop Gallery 无 `using` 即可调用，Browser Gallery 为另一个包必须显式 `using`。新包应带命名空间。 另标注两个现存包均未附字体许可文件 —— 将字体编译进程序集即构成再分发。此处仅在文档中点明，未 改动包内容，补充许可属授权决定而非文档变更。 同步接入 Guide 导航，并从 typography 架构 overview 与 font-packages 建立反向链接。
454 B
454 B
使用指南
本目录按开发任务组织 AtomUI 的使用、接入和定制说明。Guide 解释如何完成任务，但不单独定义公共 API、格式协议 或架构不变量；稳定契约分别由 Architecture、Control 文档和 Reference 拥有。