avalonia-versions 用于解决 Avalonia 开发中按版本选 API 的问题:先确认项目使用的 Avalonia 版本,再决定用哪套接口,避免把 12.x 写法放进 11.x 项目,或反之。
用途
该技能适用于几乎所有涉及 Avalonia 版本的编码任务——检测项目版本、查询某特性或 API 在 11.3、12.0、12.1 中是否存在、做跨大版本升级与迁移。技能说明建议作为第一步使用。
受支持的版本
- 12.1:最新补丁 12.1.4,12.1.0 发布于 2026 年 7 月,要求 net8.0+(推荐 net10.0,Android/iOS 必须使用),当前稳定版,新项目默认选择。
- 12.0:最新补丁 12.0.5,12.0.0 发布于 2026 年 4 月,.NET 要求同 12.1,可直接升级到 12.1。
- 11.3:最新补丁 11.3.22,支持 netstandard2.0 / net6.0+ / .NET Framework,处于仅维护的旧版本,建议规划迁移。
- 低于 11.3 的版本不在覆盖范围,可按 11.3 处理,但预期缺少部分 API。
主要能力
- 版本检测流程:按顺序在 Directory.Packages.props、.csproj、Directory.Build.props 中查找 Avalonia 版本,或用 dotnet list package 过滤、用 grep 检索 csproj/props。若尚无项目,建议 12.1.x + net10.0。所有 Avalonia. 核心包必须版本一致;ReactiveUI.Avalonia、Avalonia.Controls.WebView、DataGrid、TreeDataGrid 等按各自节奏发版,需在 NuGet 上查匹配版本。
- 版本标注约定:技能中的 API 会用 (12.0+)、(12.1+)、(11.x) 或无标注来标明适用范围;标注为 (11.x) 的 API 在 12 中已移除或过时,选择时须与项目版本匹配,不可混用。
- 特性矩阵:分平台与运行时、控件、绑定/文本/输入/线程三大类,逐项列出 11.3 / 12.0 / 12.1 的支持状态(可用、不可用、过时、实验)。例如 .NET Framework 目标仅 11.3 支持;12.0 起要求 net8.0 最低;Wayland 后端在 12.1 为实验性且不会被 UsePlatformDetect() 选中;GroupBox、PipsPager、分页导航等控件自 12.0 起提供;TableView、PlatformFeedback、X11 进程间拖放、按显示器刷新率渲染等为 12.1 新增;DataGrid 自 12.1 起进入维护模式。
- 迁移对照:给出一张 11.x → 12.x 的重命名/替换 API 表,例如 IDataObject/DataObject 改为 IAsyncDataTransfer/DataTransfer、DragDrop.DoDragDrop 改为 DoDragDropAsync、Watermark 改为 PlaceholderText、SystemDecorations 改为 WindowDecorations、Avalonia.Diagnostics 改为 AvaloniaUI.DiagnosticsSupport、Avalonia.ReactiveUI 改为 ReactiveUI.Avalonia 等,并单列在 12 中被移除、11 中已过时的 API。
- 行为变化提示:列出升级后不报编译错误但行为改变的事项,如默认开启编译绑定、数据注解校验默认关闭、触摸/手写笔在释放时才选择、Window.WindowState 为直接属性不能由样式设置、隐藏控件上的样式动画会暂停、Dispatcher.InvokeAsync 捕获 ExecutionContext、显式 UseSkia() 必须配合 UseHarfBuzz() 等。
- 12.0 → 12.1 升级说明:可直接升级,无 API 破坏;但多个脏矩形裁剪默认关闭、模板缓冲默认开启,X11 与部分 Windows 渲染模式下按显示器刷新率运行,CPU/GPU 占用可能上升;Wayland 需通过 Avalonia.Wayland 与 UseWayland() 显式启用。
- 常见错误清单:把 12.x API 写进 11.x 项目(或反之)、升级核心包却未同步 Avalonia.Desktop/Avalonia.Themes.Fluent/Avalonia.Headless.*、迁移到 12 后仍保留 Avalonia.ReactiveUI 与 Avalonia.Diagnostics、在 12.x 的 Android/iOS 目标上遗漏 net10.0、误以为 UsePlatformDetect() 会选择 Wayland。
使用方式
在开始编写 Avalonia 代码前先查阅该技能,按检测流程确定版本,再依据版本标注和特性矩阵选择 API;执行迁移时按对照表逐项替换,并注意行为变化一节列出的静默变更。
适用场景
新项目技术选型、既有项目版本排查与升级、跨大版本迁移、按版本核对控件与平台能力、排查因版本混用导致的编译或运行问题。
限制
版本信息与发布日期以资料所载为准;低于 11.3 的版本未被覆盖;第三方包版本需另行在 NuGet 查询;资料未提供该技能的具体安装命令、许可或收费信息。