简介：一份面向 .NET 桌面开发者的 Avalonia 跨平台 MVVM 示例工程，聚焦如何用 ReactiveUI 构建响应式 ViewModel 与数据绑定，适合从 WPF 迁移或初学 Avalonia/ReactiveUI 的开发者参考。压缩包采用 ZIP 格式，共 2000 个文件，主要包含 C# 源码与工程配置（cs/csproj）、依赖库与说明文档（dll/xml/pdb）以及若干跨平台编译产物，包体约 223.6MB，目前已有 1381 人学习下载。Demo 中完整演示了 ReactiveObject/ReactiveProperty 可观察属性、ReactiveCommand 命令交互、WhenAnyValue 多属性变更监听、基于 Rx 的响应式 UI 更新与异常处理等关键知识点，并配有 App.xaml、MainWindow.xaml、MainViewModel.cs、Model.cs 等工程模块，清楚展示 View 通过 DataContext 与 ViewModel 关联、属性变化自动驱动界面刷新的过程。通过学习这份工程结构，开发者可以快速掌握 Avalonia 与 ReactiveUI 结合下的 MVVM 落地写法，并据此迁移或改造自己的跨平台桌面项目。 Avalonia 项目里用 ReactiveUI 做 MVVM，这个话题这几年问的人越来越多了。很多从 WPF 迁移过来的团队，心里想的是“能不能把原有那套 MVVM 经验直接带过去”，结果一打开 Avalonia 文档，发现官方模板里赫然写着 ReactiveUI，于是顺理成章地就入了坑。但真正开始写之后，很多人又会发现：ReactiveUI 不是单纯的 INotifyPropertyChanged 封装，它把 Rx 的数据流思想整个揉进了 ViewModel 和 View 的生命周期里，用不好就是满地坑。
我自己的项目大概是在 Avalonia 0.10 时期开始尝试这套组合的，后来一路跟进到 11.x。说实话，用顺手之后，再回到普通 MVVM 框架，会有一种“工具链缺失”的感觉——尤其当你需要处理异步命令、派生属性、跨线程刷新这些场景时，ReactiveUI 把大多数脏活都收敛成了几条清晰的数据流。这篇文章不打算做成官方文档的复读机，而是把我在实际项目里怎么搭骨架、怎么写绑定、怎么排雷的过程，完整地摊开来说一遍。
1. 为什么是 Avalonia + ReactiveUI：选型复盘与价值判断
1.1 WPF 老兵的迁移直觉与 Avalonia 的真实定位
先聊一个几乎每个 WPF 开发者都会问的问题：Avalonia 跟 WPF 到底像不像？我的答案是，对于 MVVM 这一层来说，迁移成本比你想象的低得多。Avalonia 的 XAML 语法、数据绑定、样式和资源体系，基本沿用了 WPF 的思维方式，甚至连 Binding 的默认行为都高度相似。这意味着你从 WPF 带过来的结构和分层直觉，在 Avalonia 里依然有效。
但 Avalonia 真正的价值在“跨平台”三个字。它不依赖 Windows 的 DirectX 栈，而是用自己的渲染引擎在 Windows、macOS、Linux 上画界面。放到今天的环境里，一套 UI 代码能同时覆盖三端桌面，对企业内部管理软件和工业控制软件来说，诱惑力极大。更别说官方还在推进 WebAssembly 和移动端的实验性支持，哪怕暂时不上生产，至少给了一条可预期的演进路线。
这种情况下，MVVM 框架的选择就很关键。Avalonia 本身不限定 MVVM 框架，你完全可以手写 INotifyPropertyChanged，也可以用 CommunityToolkit.Mvvm。但如果你希望代码里同时体现“跨平台 UI + 响应式状态流”两种特性，ReactiveUI 是目前和 Avalonia 集成得最自然的选择。为什么？因为 Avalonia 官方在模板层面就直接接入了 ReactiveUI，View 基类、绑定扩展、生命周期钩子都是现成的，不用自己造轮子去糊接口。
1.2 ReactiveUI 和其他 MVVM 框架的本质区别
很多人把 ReactiveUI 只理解成“带数据流的 MVVM”，但它的核心其实是 Rx。传统 MVVM 框架里，属性变更就是一次事件通知，事件之间是孤立的；而 ReactiveUI 把属性变化、命令执行、用户输入这些行为全部统一成 IObservable 流。你可以对一条流做筛选、合并、节流、异常处理，再把它转换成界面关心的属性。
举个例子，搜索框场景。用普通 MVVM，你往往需要在 View 层编写 TextChanged 事件，或者用 Behavior 把事件转成命令，再在 ViewModel 里处理防抖逻辑。而在 ReactiveUI 里，搜索框的文本变化本身就是一条字符串流，你只需要告诉它“当文本变化时，给我一条延迟 300 毫秒、忽略相同值、并且只允许非空字符串通过的数据流”，后续的搜索请求就全挂在这条流上。这种表达方式比手写一堆 if/else 和计时器要严谨得多。
所以如果你是第一次接触 ReactiveUI，不要只盯着“它帮我省了多少样板代码”，更重要的是体会它如何把 UI 世界的时间性、异步性、状态变化都纳入统一抽象的。当然，这套思想的代价是学习曲线比 CommunityToolkit.Mvvm 陡不少。我的建议是：项目里已经有 Rx 基础，或者确实存在大量实时数据、异步事件、跨线程更新的场景，才值得选 ReactiveUI；如果只是简单的增删改查界面，用它反而有点用力过猛。
2. 从零搭建项目：模板、依赖注入与 ReactiveUI 启动姿势
2.1 模板创建与 NuGet 包取舍
Avalonia 官方提供了一套命令行模板，安装后可以直接生成带 ReactiveUI 的 MVVM 项目。先安装模板：
dotnet new install Avalonia.Templates然后创建一个带 MVVM 结构的项目：
dotnet new avalonia.mvvm -o DemoApp这个模板生成的项目里已经引用了 Avalonia.ReactiveUI、ReactiveUI 等包，并且把 ViewModels、Views、Models 三个目录分好了。如果你是第一次做，我建议直接用这个模板起步，省得手动配包。
如果你要手动搭建，核心依赖是下面几个：
- Avalonia：桌面运行基础。
- Avalonia.Desktop：桌面入口和渲染循环。
- Avalonia.ReactiveUI：提供 ReactiveWindow、ReactiveUserControl 等 Avalonia 专用类型，以及在 AppBuilder 上的 UseReactiveUI 方法。
- ReactiveUI：MVVM 框架主体。
- System.Reactive：Rx 基础库，ReactiveUI 依赖它。
注意没有必要一上来就加 ReactiveUI.Fody。虽然 Fody 的织入方案能让你把[Reactive] public string Name { get; set; }直接变成带通知的自动属性，看起来很爽，但它需要额外配置 FodyWeavers.xml，而且有时候会在编译期跟你开一些小玩笑。老老实实用RaiseAndSetIfChanged反而更透明。
2.2 应用启动时如何把 ReactiveUI 接进来
模板生成出的 Program.cs 大多是下面这种结构：
public static class Program { public static void Main(string[] args) { BuildAvaloniaApp() .StartWithClassicDesktopLifetime(args); } public static AppBuilder BuildAvaloniaApp() => AppBuilder.Configure<App>() .UsePlatformDetect() .WithInterFont() .LogToTrace() .UseReactiveUI(); }关键就在最后的.UseReactiveUI()。这个方法来自 Avalonia.ReactiveUI 包，它会把 ReactiveUI 的默认调度器和 Avalonia 的 UI 线程绑定起来。也就是说，你在 ViewModel 里使用RxApp.MainThreadScheduler时，它最终会落到 Avalonia 的 UI 线程上。这个绑定不是可选项，而是必须调用的初始化逻辑。如果你忘了加，异步流里更新界面属性时就可能遇到线程问题。
依赖注入方面，ReactiveUI 本身集成了 Splat 作为定位器，但现代 Avalonia 项目里更多是直接用 Microsoft.Extensions.DependencyInjection。模板项目里默认是在 App.axaml.cs 的SetupServices里注册服务。我习惯把各个服务的注册集中在一个地方：
public override void Initialize() { AvaloniaXamlLoader.Load(this); } public override void OnFrameworkInitializationCompleted() { var locator = new LocatorCurrent(); locator.Register(() => new MainViewModel()); locator.Register(() => new AuthService()); base.OnFrameworkInitializationCompleted(); }这里的LocatorCurrent是模板自定义的一个服务定位器包装，本质上还是依赖注入。实际项目里我更推荐直接用IServiceCollection，然后在 MainViewModel 的构造函数里注入需要的服务。这样单元测试时可以很干净地替换依赖。
2.3 ViewModel 基类与项目目录划分
目录结构按模板来就好：Models 放实体或服务数据，ViewModels 放页面级和控件级 ViewModel，Views 放对应的 View。唯一要提醒的是，不要在 Models 里塞业务逻辑。ReactiveUI 不代表你可以省掉分层，它只是让层与层之间的通知传播更顺滑。
ViewModel 基类一般继承ReactiveObject，这是 ReactiveUI 里最基础的响应式对象。它实现了 INotifyPropertyChanged，并且提供了RaiseAndSetIfChanged这类工具方法。页面级 ViewModel 如果需要特定生命周期处理，可以实现IActivatableViewModel接口，配合 View 的WhenActivated使用。这样界面在显示和隐藏时会回调到 ViewModel，你可以在这里订阅数据流或发起加载。
3. 核心 MVVM 实现：属性、命令和 View 绑定的落地写法
3.1 属性变更的标准写法：RaiseAndSetIfChanged
ReactiveUI 里最常用到的属性写法是这样的：
public class LoginViewModel : ReactiveObject { private string? _userName; public string? UserName { get => _userName; set => this.RaiseAndSetIfChanged(ref _userName, value); } private string? _password; public string? Password { get => _password; set => this.RaiseAndSetIfChanged(ref _password, value); } }RaiseAndSetIfChanged的内部逻辑很简单：先比较新旧值，如果引用相等就直接返回，不触发任何事件；如果改变了，就赋值并触发 PropertyChanged。这样能避免很多无意义的界面刷新。注意它比较用的是EqualityComparer<T>.Default，也就是会用类型自带的相等逻辑。如果你正在绑定的属性是自定义对象，一定要保证它的 Equals 行为符合预期，否则可能会出现“明明数据没变，界面却被刷了一遍”的现象。
有一个场景我不建议用上面这种写法：依赖其他属性做计算的“派生属性”。比如界面上的“全选”状态是IsChecked和IsIndeterminate的组合，如果你手动在不同属性的 Setter 里调用派生属性的 RaisePropertyChanged，代码会越写越乱。这种情况应该交给WhenAnyValue或ObservableAsPropertyHelper，后面第四部分会专门聊。
3.2 用 ReactiveCommand 处理异步登录逻辑
命令是 MVVM 里最磨人的部分，尤其是异步命令：要防重复点击、要支持可以执行状态、要处理异常、还要在按钮上显示加载状态。ReactiveUI 的ReactiveCommand把这些全部内置了。
看一个典型登录场景的写法：
public class LoginViewModel : ReactiveObject, IActivatableViewModel { public ReactiveCommand<Unit, Unit> LoginCommand { get; } private readonly IAuthService _authService; public LoginViewModel(IAuthService authService) { _authService = authService; var canLogin = this.WhenAnyValue( x => x.UserName, x => x.Password, (userName, password) => !string.IsNullOrWhiteSpace(userName) && !string.IsNullOrWhiteSpace(password)); LoginCommand = ReactiveCommand.CreateFromTask( async () => await _authService.LoginAsync(UserName, Password), canLogin); } }这段代码里有两个点值得特别注意。
第一，CreateFromTask默认会把命令的执行状态管理好：命令执行期间自动置为“不可执行”，所以用户疯狂连点登录按钮，只会触发第一次点击。你不需要额外维护_isLoggingIn这个布尔量。如果你还需要在界面上显示一个“登录中”的进度圈，可以直接绑定命令的IsExecuting属性。
第二，异步异常不会默默吞掉。如果LoginAsync抛出了异常，这个异常不会直接跳到界面线程导致崩溃，而是会出现在LoginCommand.ThrownExceptions流里。必须手动订阅这个流来处理错误提示，否则异常会被吞掉，表现为点按钮没反应。
LoginCommand.ThrownExceptions .Subscribe(ex => _errorMessage = ex.Message);这一点是最多人踩的坑，一定要谨记。
3.3 View 层绑定：ReactiveUserControl、x:DataType 与 WhenActivated
View 侧我建议让页面继承ReactiveUserControl<TViewModel>，而不是普通UserControl。这样做有三个好处：View 自带强类型 ViewModel 属性；支持WhenActivated生命周期；和你手工绑定DataContext的行为更一致。
一个典型的登录 View XAML 开头是这样：
<reactive:ReactiveUserControl x:Class="DemoApp.Views.LoginView" xmlns:reactive="http://reactiveui.net" xmlns:vm="using:DemoApp.ViewModels" x:DataType="vm:LoginViewModel">在 Avalonia 11 里，x:DataType是编译绑定必须的。它告诉编译器这个 View 的数据上下文类型是什么，这样才能在编译期检查绑定路径是否正确。如果你忘了设置x:DataType，很多绑定错误会延迟到运行时才暴露。
代码后置里，如果你需要在 View 显示时订阅流，可以把订阅动作放进WhenActivated，并使用返回的CompositeDisposable来管理订阅生命周期：
public LoginView() { InitializeComponent(); this.WhenActivated(disposables => { this.OneWayBind(ViewModel, vm => vm.LoginCommand.IsExecuting, v => v.Spinner.IsVisible) .DisposeWith(disposables); this.BindCommand(ViewModel, vm => vm.LoginCommand, v => v.LoginButton) .DisposeWith(disposables); }); }WhenActivated的核心价值是：当 View 被从视觉树上移除时，它会自动销毁所有订阅，从而避免内存泄漏。这是 WPF 时代最容易被忽略的问题，在 ReactiveUI 里成了默认机制。
4. 响应式数据流实战：WhenAnyValue、OAPH 与线程调度
4.1 WhenAnyValue：把多个属性变化合成一条流
很多 UI 状态不是单一属性决定的，而是多个属性组合的结果。WhenAnyValue就是为这种场景设计的：你告诉它要监听哪些属性，以及如何在属性变化后计算新值。
比如之前登录按钮的 CanExecute 逻辑，就是一个典型例子。再比如我项目里有个搜索筛选组合：
var queryStream = this.WhenAnyValue( vm => vm.SearchText, vm => vm.SelectedFilter, (text, filter) => new SearchQuery(text, filter));这样只要SearchText或SelectedFilter任一个发生变化，queryStream就会发出新的SearchQuery对象。你可以把这股流接到命令上，再配合Throttle做输入防抖：
var searchCommand = ReactiveCommand.CreateFromTask<string, List<Item>>(DoSearchAsync); queryStream .Throttle(TimeSpan.FromMilliseconds(300), RxApp.MainThreadScheduler) .InvokeCommand(searchCommand);InvokeCommand的作用是把流里的每个值作为命令参数，自动执行命令。这个模式省掉了一大堆手动处理搜索逻辑的代码。
4.2 ObservableAsPropertyHelper：把 IObservable 变成可绑定属性
ObservableAsPropertyHelper，简称 OAPH，是 ReactiveUI 里把数据流“转化为属性”的桥梁。它适合那些由其他数据流派生、但需要在界面里直接绑定的状态。
举个例子，登录命令执行中，我们想把IsExecuting直接暴露成 ViewModel 的一个只读属性，同时让按钮区显示忙碌状态：
private readonly ObservableAsPropertyHelper<bool> _isBusy; public bool IsBusy => _isBusy.Value; // 在构造函数中 _isBusy = LoginCommand.IsExecuting .ToProperty(this, vm => vm.IsBusy);ToProperty会订阅前面的 IObservable，并且每次值变化时都会触发 ViewModel 的 PropertyChanged 事件。绑定端零负担：XAML 里直接写IsBusy就可以了。
要注意的是，OAPH 实例本身必须被 ViewModel 的一个字段引用，避免被垃圾回收。如果_isBusy是局部变量，它创建的订阅很可能在一段时间后失效，表现就是界面偶尔不更新。这类问题很难排查，所以写 OAPH 时一定要养成字段持有它的习惯。
4.3 我在实际项目中踩过的数据流坑
第一个坑：嵌套属性表达式不能用简单的 WhenAnyValue 监听。WhenAnyValue(x => x.User.Address.City)并不会在User或Address变化时自动重新求值，它只监听表达式链上的最后一个属性。如果你真的要监听“链式对象关系”，需要用WhenAny逐步展开：
this.WhenAny( vm => vm.User, vm => vm.User!.Address, vm => vm.User!.Address!.City, (_, _, city) => city);这个问题在数据结构比较深的项目里非常容易踩，而且表现很隐蔽：第一次进入页面时值是对的，切到另一个用户之后，界面里的城市还是旧值。
第二个坑：订阅被 Disposable 收了，但 Dispose 时机不对。DisposeWith(disposables)并不是魔法，它只是把订阅加入了一个 CompositeDisposable。这个 disposable 的生命周期由WhenActivated控制：页面隐藏时释放，再次显示时重新订阅。所以如果你在构造函数里用WhenActivated外的代码创建订阅，它们就不会自动释放，最终导致泄漏。
第三个坑：异步流更新 UI 时忘记调度。后台线程跑完运算，直接给 ViewModel 属性赋值，界面上有时更新、有时不更新，甚至偶发崩溃。根源就是没有切回 UI 线程。ReactiveUI 的标准解法是：
Observable.Start(DoHeavyWork, RxApp.TaskpoolScheduler) .ObserveOn(RxApp.MainThreadScheduler) .Subscribe(result => SearchResult = result);ObserveOn(RxApp.MainThreadScheduler)保证订阅回调跑在 UI 线程，属性变更引发的事件也就能安全地触发界面刷新。
5. 避坑清单与可测试性：让跨平台 MVVM 项目立得住
5.1 绑定失效：先怀疑 DataContext，再怀疑路径
Avalonia 开发里最让人头大的不是写代码，而是 XAML 引用了一个不存在的路径，编译期不报错，运行期整个控件不刷新。我的排查顺序始终是：先看x:DataType是否和 ViewModel 类型一致；再看 View 是否设置了 DataContext；最后看绑定路径首字母是不是大写。这三个环节只要错一个，绑定就会静默失败。
如果你在 View 构造里手动DataContext = new LoginViewModel()，那么x:DataType不会代替它，只是编译期提示。实际运行时 DataContext 还是会被你手动赋值覆盖。这种不一致的问题在代码一多之后特别容易出现，所以我在项目里定了条规矩：所有 DataContext 都通过 ViewModelLocator 或 View 的构造函数注入，禁止手写DataContext = new ...这种写法。
5.2 线程调度：不要在后台线程直接碰 UI 状态
跨平台项目最容易爆炸的地方就是线程。Avalonia 虽然跨平台，但 UI 线程模型依然是单一的。ReactiveUI 帮我们统一了调度器，但前提是你遵循规则：凡是订阅回调里要改 ViewModel 属性，前面一定要有ObserveOn(RxApp.MainThreadScheduler)。如果是数据库或网络回调，建议在源头就把流映射到后台线程执行，最后再切回 UI 线程。
这里的经验是不要省那一行ObserveOn。我见过太多因为图省事然后在不同平台偶现崩溃的问题。窗口大小、消息弹窗、列表滚动，这些通通依赖 UI 线程。守住了调度，就守住了一大半跨平台兼容性。
5.3 可测试性：不启动界面也能验证 ViewModel 逻辑
ReactiveUI 项目的另一个优势是“可测性深入到数据流层面”。测试一个 ViewModel，不再需要去模拟 UI 点击，而是直接触发数据流。
写一个简单的登录 ViewModel 测试：
[Fact] public void 用户名密码均填好时_登录命令可执行() { var authService = new Mock<IAuthService>(); authService.Setup(x => x.LoginAsync(It.IsAny<string>(), It.IsAny<string>())) .ReturnsAsync(true); var vm = new LoginViewModel(authService.Object); Assert.False(vm.LoginCommand.CanExecute(null)); vm.UserName = "admin"; vm.Password = "123456"; Assert.True(vm.LoginCommand.CanExecute(null)); }这里LoginCommand.CanExecute由WhenAnyValue生成的流驱动，并不需要启动 Avalonia 窗口。配合ReactiveUI.Testing包，还可以用TestScheduler控制时间，测试 Throttle、延迟等操作符。这样连“搜索输入防抖”这种以前很难测的场景，都能写成一个稳定的单元测试。
5.4 从桌面端向更多平台移植的代码分层思考
最后聊点远期的事。Avalonia 11 已经支持了 WebAssembly，移动端的支持也在逐步完善。这意味着你今天的桌面 MVVM 代码，未来有可能不重新实现就跑到浏览器和移动设备上。前提是你把 ViewModel 层和平台依赖严格隔离开。
拿文件读写来说，不要在 ViewModel 里直接用System.IO.File，而是抽象一个IFileStorageService，桌面实现用System.IO，未来 Web 实现可以换成浏览器文件 API。ReactiveUI 不会替你做架构，它只是让 ViewModel 层的数据流更干净。真正决定跨平台能力的，还是你对职责边界的把控。
我现在实际项目里的做法是：View 层只放视觉逻辑和 ToString 之类的方法；ViewModel 层只操作服务接口和 ReactiveCommand；所有平台差异都藏在接口实现后面。这样一来，哪怕未来真的要做 Avalonia Web 版本，我要动的也只是注册服务的代码而已。如果以后再遇到类似的技术选型问题，我会建议你先想清楚核心场景是“数据流丰富”还是“普通表单”，再决定上不上 ReactiveUI。对合适的问题来说，这套组合是真的顺手。
本文还有配套的精品资源，点击获取
