SuperAPI AI 工具集

avalonia-wpf-migration

编程与开发

查看项目

更新于 11-03 16:15

技能介绍

该技能面向正在把 WPF 应用迁移到 Avalonia 的开发者,也适合需要对照两套框架 API、理解行为差异的场景。内容以速查表和代码对照为主,帮助把 WPF 概念映射到 Avalonia 的对应实现。

版本与目标框架:目标为 Avalonia 12.x(建议 12.1.x),11.x 相关说明会单独标注。Avalonia 12 要求 net8.0+(推荐 net10.0),不支持 .NET Framework 和 netstandard2.0 目标;仍在 .NET Framework 上的 WPF 应用需先重定向到现代 .NET,Avalonia 11.3 是最后支持这些旧目标框架的版本线。

主要映射内容:

  • 文件与命名空间:.xaml 变为 .axaml,根命名空间改为 https://github.com/avaloniaui。
  • 类型与属性:DependencyProperty 对应 StyledProperty 或 DirectProperty;FrameworkElement 对应 Control;无外观控件基类用 TemplatedControl;UserControl 名称与 API 相近。
  • 样式系统:WPF 中带 TargetType 的 Style 用于无外观控件时,改用带 x:Key 的 ControlTheme;Avalonia 没有 Triggers,改用选择器伪类(如 Button:pointerover)或嵌套样式;DataTrigger 改为绑定加伪类或 Classes 绑定。
  • 绑定语法:RelativeSource AncestorType 改为 $parent[TypeName].Property,Self 改为 $self.Property;TemplateBinding、x:Static、IValueConverter、IMultiValueConverter、ObservableCollection<T>、ICommand 基本一致。
  • 资源与图片:pack://application:,,,/ 改为 avares://AssemblyName/,ResourceDictionary Source 改为 ResourceInclude;BitmapImage+Uri 改用 Bitmap 与 AssetLoader。
  • 窗口与对话框:Window.ShowDialog() 需传入 owner;没有内置 MessageBox,可用社区库或自建对话框窗口;文件对话框使用 StorageProvider,通知使用 WindowNotificationManager;WindowStyle 类调整改用 WindowDecorations(12.0+)。
  • 线程调度:Dispatcher.Invoke 改为 await Dispatcher.UIThread.InvokeAsync 或 Dispatcher.UIThread.Post。
  • 数据集合与控件:没有 CollectionViewSource 等价物,排序、筛选、分组放到 ViewModel(如 DynamicData、LINQ),DataGridCollectionView 仅用于 DataGrid;GroupBox 在 12.0+ 可用;ListView+GridView 的只读列场景可用 TableView(12.1+),或在 12.0/11.x 用 DataGrid/TreeDataGrid,DataGrid 处于维护模式且位于独立包 Avalonia.Controls.DataGrid;TextBox 水印用 PlaceholderText(12.0+);剪贴板与拖放改用 DataTransfer/DataTransferItem(12.0+)与 DragDrop.DoDragDropAsync,剪贴板 API 为异步。
  • 绑定编译:12.0+ 默认启用编译绑定,根或 DataTemplate 需加 x:DataType,否则 {Binding Name} 无法编译;可改用 {ReflectionBinding Name},或设置 AvaloniaUseCompiledBindingsByDefault 为 false;数据注解验证需显式开启。
  • MVVM 框架:ReactiveUI 在 12.x 使用 ReactiveUI.Avalonia 包(12 不再有 Avalonia.ReactiveUI);CommunityToolkit.Mvvm 用法不变。

可直接复用的部分:INotifyPropertyChanged、ICommand、ObservableCollection<T>、IValueConverter、多数 MVVM 框架代码、Grid/StackPanel/DockPanel 布局,以及 ItemsControl、ListBox 等相似 API。

常见错误包括:沿用 WPF Trigger 语法、使用 pack:// URI、调用 MessageBox.Show()、以 net48/netstandard2.0 为目标、12 中无 x:DataType 的 {Binding}、以 FrameworkElement 为基类、ControlTheme 缺 x:Key 导致模板不生效。

限制:资料为技能说明与迁移速查,未提供安装命令、收费方式或运行环境要求之外的平台信息;具体 API 行为以对应 Avalonia 版本文档为准。