官网：https://avaloniaui.net/
文档：https://docs.avaloniaui.net/docs/welcome

环境安装

1、Visual Studio 2026安装

下载地址：https://visualstudio.microsoft.com/zh-hans/downloads/
社区版即可

2、.net framework安装

下载地址：https://dotnet.microsoft.com/zh-cn/download/dotnet-framework
安装Visual Studio 2026的时候会自动安装一个版本，如果需要其他版本，可以在这里下载

3、Avalonia for Visual Studio

扩展 -> 管理扩展 （https://docs.avaloniaui.net/docs/get-started/set-up-your-ide）
如果直接点击安装有问题，可以直接去浏览器下载好了再安装：
https://marketplace.visualstudio.com/items?itemName=AvaloniaTeam.AvaloniaVS

4、安装官方模板

https://docs.avaloniaui.net/docs/get-started/install-avalonia

dotnet new install Avalonia.Templates
dotnet new list

项目创建

1、模板选择

模板名称	架构模式	目标平台	核心特点	适用场景
1. Avalonia .NET App	非 MVVM (Code-Behind)	纯桌面 (Win/Linux/macOS)	极简模式。 无 ViewModel，UI 和逻辑写在同一个 .axaml.cs 文件中。	学习 Avalonia 基础、制作几行代码的微型工具、快速验证某个控件的用法。适合有WinForm开发基础
2. Avalonia .NET MVVM App	MVVM (CommunityToolkit)	纯桌面 (Win/Linux/macOS)	标准桌面开发首选。 自带 ViewModel 和数据绑定，UI 与逻辑分离，结构清晰。	绝大多数商业级桌面应用（如后台管理工具、单机游戏客户端、桌面实用工具）。适合有WPF开发基础
3. Avalonia Cross Platform App	MVVM (CommunityToolkit)	全平台 (桌面 + 手机 + Web)	终极跨平台。 一套代码生成桌面、Android、iOS、WebAssembly 等多个子项目。	需要将软件同时发布到电脑、手机和网页的大型商业产品。

2、MVVM框架选择

在 Avalonia 的 MVVM 开发中，CommunityToolkit.Mvvm（微软官方维护）和 ReactiveUI（Avalonia 官方深度集成）是两大主流框架。两者没有绝对的优劣之分，核心区别在于编程范式和适用场景。

维度	CommunityToolkit.Mvvm	ReactiveUI
设计哲学	传统命令式 + 源生成器，极简轻量	函数响应式编程 (FRP)，流式数据管道
学习曲线	⭐ 极低（传统 C# 思维，几分钟上手）	⭐⭐⭐⭐ 较高（需理解 Observable、LINQ 式操作符）
代码风格	[ObservableProperty], [RelayCommand] 属性标注	this.WhenAnyValue(), .Select(), .Subscribe() 链式调用
异步处理	async Task + [RelayCommand] 自动封装	CreateAsyncTaskCommand() / ReactiveCommand.CreateFromTask()
复杂状态联动	手动在 setter 中调用其他方法/更新属性	声明式管道，多条件组合 (CombineLatest, Merge) 极其优雅
性能	编译时生成代码，零反射，极致性能	运行时订阅/调度，有轻微开销（绝大多数场景可忽略）
Avalonia 集成	原生支持绑定，无特殊依赖	Avalonia 官方深度集成，内置 RoutedViewHost, ViewModelViewHost 等控件
生态/文档	微软官方维护，文档完善，社区庞大	历史悠久，Avalonia/WPF 老牌方案，文档丰富但部分过时
包体积	~50KB (仅源码生成器)	~2MB+ (含 System.Reactive 等依赖)

新建项

模板名称	继承自	核心作用与特点	最佳适用场景
Avalonia Window	Window	独立的主窗口。 自带系统标题栏、最小化/最大化/关闭按钮，在系统任务栏有独立图标。	桌面应用的主程序窗口、独立的多文档窗口。
Avalonia UserControl	UserControl	可复用的自定义 UI 控件块。 没有独立窗口框架，必须嵌套在 Window 或 Page 内部。	页面内的局部功能模块（如：导航栏、数据表格、用户信息卡片）。开发中最常用。
Avalonia TemptedControl	TemplatedControl	自定义外观和行为的原生控件。 不写死 UI 结构，仅定义控件状态（如：按下、鼠标悬停），UI 交给使用者自定义。	开发复杂的第三方 UI 控件库，或需要高度定制外观的通用控件。
Avalonia ContentPage	ContentPage	移动端/多页面的标准内容页。 专为移动端（Android/iOS）和路由导航设计的页面容器。	跨平台 App 的移动端独立页面，通常配合路由导航框架使用。
Avalonia DrawerPage	DrawerPage	侧滑/抽屉页面。 类似移动端 App 的“侧边栏”或“抽屉菜单”（Drawer），通常从屏幕侧边滑出。	App 的侧边导航菜单、移动端的功能面板。
Avalonia NavigationPage	NavigationPage	提供导航栏的页面容器。 自带顶部导航栏（类似 iOS 的导航控制器），提供前进/后退和标题。	移动端 App 的多级页面跳转，提供统一的顶部导航条。
Avalonia TabbedPage	TabbedPage	标签页页面容器。 提供底部的标签栏（Tab Bar），可以在多个 ContentPage 之间无缝切换。	App 底部的 Tab 切换（如微信底部的“微信/通讯录/发现/我”）。
Avalonia Resource Dictionary	ResourceDictionary	UI 资源集合文件。 不包含 UI 界面，只存放颜色、画刷、图标路径等可复用的静态资源。	统一管理应用的颜色主题、图标资源，实现换肤功能。
Avalonia Styles	Styles	全局或局部样式文件。 专门用于编写控件的样式（Style）和模板（ControlTemplate）。	全局修改按钮、文本框等原生控件的默认外观，统一管理 UI 风格。

1. 桌面端开发必用

如果你只做 Windows/macOS 桌面软件，Avalonia Window 和 Avalonia UserControl 是你每天都要用的两个核心模板。

• 主界面：新建 Window。
• 界面里的各个模块：新建 UserControl 然后塞进 Window 里。
• 建议：日常开发 95% 的情况只需要这两个。

2. 移动端/全平台开发才用

ContentPage、DrawerPage、NavigationPage、TabbedPage 是移动端/跨平台导航专用的模板。

• 注意：如果在纯桌面项目中用错了它们（比如试图在 Window 内部直接塞一个 ContentPage 而不配合路由导航框架），就会导致界面显示不出来的“坑”。

3. 进阶封装控件才用

TemplatedControl 是给高级开发者用的。如果你只是想把几个现有的按钮和文本框拼在一起，直接用 UserControl 就够了，不要去碰 TemplatedControl。

4. 全局样式管理

当你的项目超过 3 个页面，或者开始做“亮色/暗色”主题切换时，立刻建立 Avalonia Resource Dictionary 和 Avalonia Styles，把颜色和样式抽离出来，这是专业 Avalonia 项目的标准做法。