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 建立反向链接。
Documentation Language: English | 简体中文
Overview
AtomUI is an Ant Design 6 component system for Avalonia/.NET desktop applications. It brings Ant Design's enterprise interaction patterns, visual language, design tokens and theme customization model to native cross-platform apps on Windows, macOS and Linux.
The project includes production-oriented desktop controls, icon packages, font packages, native window integration, DataGrid, ColorPicker and source generators for custom controls, tokens and localization. Feedback, issues and pull requests are welcome.
Features
- Ant Design 6 experience adapted for native Avalonia desktop applications.
- A broad set of ready-to-use controls for enterprise software, including layout, navigation, data entry, feedback, data display and optional advanced packages.
- Token-driven theming built on Avalonia's style and resource system, with support for consistent customization across controls.
- Cross-platform desktop support for Windows, macOS and Linux with a shared .NET/XAML development model.
- Source generators for custom controls, theme tokens and localization to reduce repetitive infrastructure code.
Requirements
.NET 8 or later (development supports .NET 10)
Avalonia 12.1.1
Windows, macOS and Linux
Latest Release Notes
AtomUI 6.1.3 adds the new Calendar, generated localization catalogs with official Portuguese (Brazil) support, expanded navigation and data-entry controls, and compatibility with Avalonia 12.1.1. Review the Changelog for release details.
Incubator
Thanks to Tongming Lake Center for their incubation support of AtomUI OSS
Community
| Telegram | WeChat Group | QQ Group | |
|---|---|---|---|
 |
 |
 |
 |
Get Started
Add NuGet packages
AtomUI is distributed through NuGet. Install the main desktop controls package first, then add optional packages such as DataGrid and ColorPicker only when your application needs them. The examples below use the latest project version.
The packages we have released are as follows:
| Package | Description |
|---|---|
| AtomUI.Native | Native platform infrastructure |
| AtomUI.Core | Core infrastructure — theme system, token system and animations |
| AtomUI.Fonts.AlibabaSans | Alibaba Sans font package |
| AtomUI.Fonts.AlibabaPuHuiTi | Alibaba PuHuiTi font package |
| AtomUI.Icons.Shared | Icon infrastructure |
| AtomUI.Icons.AntDesign | Ant Design icon package |
| AtomUI.Controls.Shared | Shared interfaces and enums for control development |
| AtomUI.Controls | Base controls and shared control capabilities |
| AtomUI.Desktop.Controls | Desktop control library — the main package |
| AtomUI.Desktop.Controls.DataGrid | DataGrid control (opt-in) |
| AtomUI.Desktop.Controls.ColorPicker | ColorPicker control (opt-in) |
| AtomUI.Generator | Source generators for custom controls, tokens and localization |
dotnet add package AtomUI.Desktop.Controls --version 6.1.3
dotnet add package AtomUI.Desktop.Controls.DataGrid --version 6.1.3
dotnet add package AtomUI.Desktop.Controls.ColorPicker --version 6.1.3
You can also install the packages from your IDE's NuGet package manager. In Rider, open:
NuGet -> Packages
Search for "AtomUI" and install the packages your project needs.
Before installation, check "Frameworks" and "Dependencies" in the package details to confirm compatibility with your target framework and Avalonia version.
Enable AtomUI library
Project Configure
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<BuiltInComInteropSupport>true</BuiltInComInteropSupport>
<ApplicationManifest>app.manifest</ApplicationManifest>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="AtomUI.Desktop.Controls" Version="6.1.3"/>
<PackageReference Include="AtomUI.Desktop.Controls.DataGrid" Version="6.1.3"/>
<PackageReference Include="AtomUI.Desktop.Controls.ColorPicker" Version="6.1.3"/>
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1"/>
</ItemGroup>
</Project>
Program.cs Configure
using Avalonia;
using System;
using AtomUI;
using ReactiveUI.Avalonia;
namespace AtomUIProgressApp;
internal class Program
{
[STAThread]
public static void Main(string[] args) => BuildAvaloniaApp()
.StartWithClassicDesktopLifetime(args);
public static AppBuilder BuildAvaloniaApp()
{
return AppBuilder.Configure<App>()
.UseReactiveUI()
.UseAtomUIPlatformDetect()
.WithAtomUIDefaultOptions()
.WithDeveloperTools()
.LogToTrace();
}
}
Enable AtomUI in the Application Class
using AtomUI;
using AtomUI.Desktop.Controls;
using AtomUI.Localization;
using AtomUI.Theme;
using Avalonia;
using Avalonia.Markup.Xaml;
public partial class App : Application
{
public override void Initialize()
{
AvaloniaXamlLoader.Load(this);
this.UseAtomUI(builder =>
{
builder.UseLanguages(
LanguageTags.EnUS,
[LanguageTags.EnUS, LanguageTags.ZhCN, LanguageTags.ZhTW]);
builder.WithDefaultTheme(IThemeManager.DEFAULT_THEME_ID);
builder.UseAlibabaSansFont();
builder.UseDesktopControls();
builder.UseDesktopColorPicker(); // optional
builder.UseDesktopDataGrid(); // optional
});
}
}
To make the first rendered frame use the dark theme, configure the initial theme algorithm in the builder:
this.UseAtomUI(builder =>
{
builder.WithDefaultTheme(IThemeManager.DEFAULT_THEME_ID, ThemeAlgorithm.Dark);
builder.UseDesktopControls();
});
SetDarkThemeMode(true) is intended for runtime theme switching after AtomUI has been initialized.
Start building with AtomUI
After AtomUI is registered, you can use AtomUI controls and Ant Design icons directly in XAML.
<atom:Window xmlns="https://github.com/avaloniaui"
xmlns:atom="https://atomui.net"
xmlns:antdicons="https://atomui.net/icons/antdesign">
<atom:Space Orientation="Horizontal">
<atom:Button ButtonType="Primary">Get Started</atom:Button>
<atom:Button Icon="{antdicons:AntDesignIconProvider StarOutlined}">Star on GitHub</atom:Button>
</atom:Space>
</atom:Window>
All Control Gallery
You can launch the gallery project locally to browse the available controls, usage patterns, examples and generated documentation.
git clone https://github.com/AtomUI/AtomUI.git
cd AtomUI
dotnet run --project controlgallery/AtomUIGallery.Desktop/AtomUIGallery.Desktop.csproj
Simple Examples
The gallery is intentionally comprehensive. If you prefer compact starter projects, visit:
These samples show smaller application setups that are easier to copy into a new project.
Acknowledgements
Ant Design
Avalonia OSS
License Description
Projects using AtomUI OSS must comply with LGPL v3. Commercial applications, including internal company software, personal commercial products and outsourced projects, may use AtomUI for free when linking to the published binaries. If you customize AtomUI from source code, you must either open source the modified code under the license terms or purchase a commercial license. For commercial licensing, contact Beijing Qinware Technology Co., Ltd.
Special thanks
RoutinAI
🤝 Contributing
Contributions of all types are more than welcome, if you are interested in contributing code, feel free to check out our GitHub Issues to get stuck in to show us what you’re made of.
