企业官网建设流程全解析

如何参与 AtomUI 开源项目：从构建源码到贡献第一个控件的完整开发者指南

【免费下载链接】AtomUIAn enhancement and extension library for Avalonia, bringing the Ant Design design language, modern controls, theming, native integrations, and cross-platform UI capabilities to .NET desktop apps.项目地址: https://gitcode.com/gh_mirrors/at/AtomUI

AtomUI 是一个为 Avalonia/.NET 桌面应用打造的 Ant Design 6 风格开源组件库，提供企业级控件、主题 Token 系统、图标字体包与跨平台 UI 能力。本文是一份面向新手贡献者的 AtomUI 开源项目贡献指南：你将学会如何搭建环境、构建源码、运行 Gallery 示例应用，并完整走通「贡献第一个控件」的流程——从阅读规范、实现控件、补充测试到提交文档，每一步都有可操作的说明。

一、先认识项目结构：你的贡献将落在哪里

克隆仓库后，你会看到这样几个核心区域（详见项目根目录 AGENTS.md）：

工程规范的统一入口在 docs/engineering/overview.md，贡献前建议先浏览一遍。

二、环境准备：三步装好开发环境

AtomUI 要求.NET 10 SDK（仓库 global.json 锁定10.0.300，允许latestFeature向前滚动）和 Avalonia 12.1.1，支持 Windows、macOS 与 Linux 三端开发。

1. 安装 .NET 10 SDK：到官方渠道下载 .NET 10.0.3xx 版本的 SDK 并验证dotnet --version。
2. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/at/AtomUI.git cd AtomUI

3. 恢复依赖并构建：

dotnet restore AtomUI.slnx dotnet build AtomUI.slnx

首次构建会触发AtomUI.Generator源码生成器（Token、注册、本地化等样板代码均由其生成，无需手写）。

三、运行源码：启动 Gallery 看全部控件

Gallery 是 AtomUI 的官方示例集，跑起来它就是一块「活的文档」。桌面宿主位于controlgallery/AtomUIGallery.Desktop/：

dotnet run --project controlgallery/AtomUIGallery.Desktop/AtomUIGallery.Desktop.csproj

启动后你可以逐个浏览 Button、Select、DataGrid、Upload 等 ShowCase 页面（源码分布在controlgallery/AtomUIGallery/ShowCases/下，按 DataDisplay、DataEntry、Navigation 等分类组织）。页面结构规范见 docs/gallery/authoring/gallery-showcase-design-pattern.md。

💡 想验证完整发布链路，可参考controlgallery/AtomUIGallery.Desktop/scripts/PublishToLocal.ps1脚本，它支持本地打包与 NativeAOT 发布。

四、找到适合新手的贡献切入点

第一次参与 AtomUI 开源项目，不必一上来就写大控件，推荐按难度递进：

1. 修文档：docs/controls/下每个控件都有overview.md、implementation.md、changelog.md，补充说明是零风险起点。
2. 报 Issue / 修 Bug：按 BUG Issue 规范 提交，写清复现步骤、当前行为与期望行为。
3. 加 ShowCase 示例：为已有控件补充演示用例，熟悉 Gallery 页面模型。
4. 贡献新控件：完成前三步后，就可以挑战完整控件了。

五、贡献第一个控件：完整开发流程

以src/AtomUI.Desktop.Controls/DatePicker/为参照，一个标准控件包含五部分：

• 控件主文件：DatePicker.cs，承载公共 API、属性注册与事件；
• Token 文件：如DatePickerToken.cs，定义专属设计 Token；
• 主题文件：Themes/目录下的.axaml主题，实现视觉样式；
• 本地化资源：Localization/下的en_US.cs、zh_CN.cs等；
• 配套文档：docs/controls/desktop/<分类>/<控件>/目录。

动手前必读两份核心规范：

• 📐 控件研发标准规范：API 兼容性红线（不得擅改既有 public 契约）、文件拆分建议、Semantic Part 设计；
• 📝 控件文档规范：文档目录结构与写作要求。

开发自检清单

• 在tests/AtomUI.Desktop.Controls.Tests/对应目录补充测试（按控件名建同名测试目录）；
• 在 Gallery 新增 ShowCase 页面并注册；
• 同步更新控件docs目录与changelog.md；
• 遵循 AOT 编程规范——把 AOT 兼容性当作一等设计约束；
• 本地跑通针对性测试：

dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 git diff --check

常见注意事项

• 🚫不要破坏 API：重命名、删除任何public成员都视为破坏性变更，必须事先在 PR 中说明理由；
• ✅AOT 优先：避免反射与动态注册，样板代码交给AtomUI.Generator源码生成器；
• ✅范围克制：一次 PR 只做一件事，理解受影响模块再改代码。

六、常见问题速答

Q：构建失败，提示 SDK 版本不匹配？检查dotnet --version是否为 10.0.3xx，global.json 已开启rollForward: latestFeature，升级小版本即可。

Q：只想改 UI 效果，要动 Token 吗？先查该控件token.md；视觉样式统一走 Token 驱动的主题系统，不要在模板里写死颜色值。

Q：如何确认改动没有影响其他控件？运行对应测试项目（AGENTS.md中列出了四条常用dotnet test命令），高风险改动建议再走一次 NativeAOT 发布验证。

总结：你的贡献之路

🎯 从环境准备到首个控件，路径非常清晰：装 .NET 10 → 克隆构建 → 跑起 Gallery → 从小改动练手 → 按规范交付完整控件。AtomUI 欢迎每一类贡献：控件实现、Bug 修复、示例补全与文档完善都值得提交。现在打开终端，clone 仓库，开始你的第一次构建吧！

【免费下载链接】AtomUIAn enhancement and extension library for Avalonia, bringing the Ant Design design language, modern controls, theming, native integrations, and cross-platform UI capabilities to .NET desktop apps.项目地址: https://gitcode.com/gh_mirrors/at/AtomUI