maui-current-apis

.NET MAUI 当前 API — 护栏技能

此技能可避免生成使用已弃用、过时或已移除 API 的代码。 在编写任何 .NET MAUI、Blazor Hybrid 或 MauiReactor 代码之前，请先阅读此内容。

推理框架

生成任何与 MAUI 相关的代码前，请遵循以下步骤：

步骤 1 — 检测目标框架

读取项目的 .csproj 文件，找到 <TargetFramework> 或 <TargetFrameworks>：

<TargetFramework>net10.0-android</TargetFramework>


<TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>

版本号（net10.0、net9.0、net8.0）决定了哪些 API 可用。 始终以项目文件中的版本为目标 — 切勿假定版本。

步骤 2 — 检测库版本

扫描 <PackageReference> 条目和 <ItemGroup>，查找关键包：

包	说明
Microsoft.Maui.Controls	MAUI 版本（如有显式指定）
CommunityToolkit.Maui	Toolkit 版本 — 不同主版本之间的 API 会发生变化
CommunityToolkit.Mvvm	MVVM Toolkit 版本 — 使用 WeakReferenceMessenger 时需要
Reactor.Maui	MauiReactor 版本 — v3+ 与 v2 的 API 不同
Microsoft.AspNetCore.Components.WebView.Maui	Blazor Hybrid 版本

如果没有显式列出 MAUI 包版本，则 MAUI SDK 版本与 <TargetFramework> 中的 .NET 版本相同。

步骤 3 — 验证 API 是否为当前版本

使用任何 API 前，请先自问：

1. 此 API 在检测到的版本中是否存在？ 如果不确定，请优先采用较新的模式。
2. 这是 Xamarin.Forms API 吗？ MAUI 的 API 范围不同 — 切勿假定与 Xamarin.Forms 兼容。
3. 此 API 是否列在下方的弃用表中？ 如果是，请使用替代方案。
4. 我是否使用了 Compatibility 命名空间？ Microsoft.Maui.Controls.Compatibility.* 类型是迁移辅助工具，不建议用于新代码。

步骤 4 — 应用决策规则

• 新旧形式同时存在时，始终使用较新的形式。
• 切勿生成 using Xamarin.Forms 或 using Xamarin.Essentials — 它们不属于 MAUI。
• 新项目中切勿使用 Compatibility 命名空间（Compatibility.RelativeLayout、Compatibility.StackLayout 等）。
• 同步名称和异步名称的版本同时存在时，优先使用异步方法名称（例如，使用 DisplayAlertAsync 而不是 DisplayAlert）。
• 使用 CommunityToolkit 或第三方 API 前，先检查项目的 NuGet 版本。

---

已弃用 API 表 — .NET MAUI 10

控件

❌ 已弃用 / 已移除	✅ 替代方案	备注
ListView	CollectionView	ListView、EntryCell、ImageCell、SwitchCell、TextCell、ViewCell 和 Cell 在 .NET 10 中均已弃用
TableView	CollectionView 或自定义布局	在 .NET 10 中已弃用
Frame	Border	Frame 是 Xamarin.Forms 的旧版控件；Border 是 MAUI 的替代方案，并支持 StrokeShape
Compatibility.RelativeLayout	Grid	仅用于迁移；已从 .NET 10 模板中移除
Compatibility.StackLayout	VerticalStackLayout / HorizontalStackLayout	兼容性 StackLayout 封装了 Xamarin 布局逻辑。使用原生 MAUI 堆栈布局可获得更好的性能

手势与输入

❌ 已弃用 / 已移除	✅ 替代方案	备注
ClickGestureRecognizer	TapGestureRecognizer	在 .NET 10 中已移除
Accelerator	KeyboardAccelerator	在 .NET 10 中已从 Microsoft.Maui.Controls 移除

页面与导航

❌ 已弃用 / 已移除	✅ 替代方案	备注
Page.IsBusy	ActivityIndicator	IsBusy 在 .NET 10 中已过时；请使用显式的活动指示器
DisplayAlert()	DisplayAlertAsync()	同步命名的版本已弃用；请使用异步版本
DisplayActionSheet()	DisplayActionSheetAsync()	同上
MessagingCenter	WeakReferenceMessenger（CommunityToolkit.Mvvm）	在 .NET 10 中已设为内部成员

动画

❌ 已弃用 / 已移除	✅ 改用	说明
FadeTo()	FadeToAsync()	在 .NET 10 中，所有动画扩展方法均重命名为 *Async
RotateTo()、ScaleTo()、TranslateTo() 等	RotateToAsync()、ScaleToAsync()、TranslateToAsync() 等	同样的模式——RelRotateTo → RelRotateToAsync、RelScaleTo → RelScaleToAsync、LayoutTo → LayoutToAsync

设备与平台 API

❌ 已弃用 / 已移除	✅ 改用	说明
Device.RuntimePlatform	DeviceInfo.Platform	整个 Device 类均已弃用
Device.BeginInvokeOnMainThread()	Dispatcher.Dispatch()	使用视图或应用的 Dispatcher 属性
Device.InvokeOnMainThreadAsync()	Dispatcher.DispatchAsync()	同上
Device.OpenUri()	Launcher.OpenAsync()	使用 Microsoft.Maui.ApplicationModel.Launcher
Device.StartTimer()	Dispatcher.StartTimer() 或 PeriodicTimer	使用调度程序或标准 .NET 计时器
DependencyService	通过 IServiceProvider 进行构造函数注入	在 MauiProgram.cs 中通过 builder.Services 注册服务

XAML 与标记

❌ 已弃用 / 已移除	✅ 改用	说明
FontImageExtension（XAML 标记扩展）	FontImageSource（类型）	使用 <FontImageSource> 元素或属性语法
Color.FromHex()	Color.FromArgb()	FromHex 已过时

安全区域与布局

❌ 已弃用 / 已移除	✅ 改用	说明
Page.UseSafeArea（iOS 平台特定）	SafeAreaEdges 属性	.NET 10 中新增；所有平台上的 ContentPage 默认值均为 None（延伸至屏幕边缘）
Layout.IgnoreSafeArea	SafeAreaEdges 属性	使用统一的安全区域 API

无障碍功能

❌ 已弃用 / 已移除	✅ 改用	说明
AutomationProperties.Name	SemanticProperties.Description	AutomationProperties 仍可使用，但 SemanticProperties 是 MAUI 原生方式
AutomationProperties.HelpText	SemanticProperties.Hint	同上
iOS SetAccessibilityHint / SetAccessibilityLabel（兼容性扩展）	Microsoft.Maui.Platform.UpdateSemantics()	在 .NET 10 中已弃用

NuGet 包

❌ 已弃用的包	✅ 改用	说明
Xamarin.Forms	Microsoft.Maui.Controls	API 表面完全不同
Xamarin.Essentials	内置 MAUI API（Microsoft.Maui.Devices、Microsoft.Maui.ApplicationModel 等）	Essentials 已并入 MAUI
Xamarin.CommunityToolkit	CommunityToolkit.Maui	命名空间和 API 表面不同
Microsoft.Toolkit.Mvvm	CommunityToolkit.Mvvm	包已重命名

---

MauiReactor 特定指南

MauiReactor v3+（适用于 .NET MAUI 9/10）：

• 热重载：v3+ 通过 .csproj 中的 <RuntimeHostConfigurationOption> 使用功能开关。不要在 MauiProgram.cs 中调用 v2 的 EnableMauiReactorHotReload()。
• API 封装：MauiReactor 会自动生成 MAUI 控件的 C# 封装。当某个 MAUI 控件已弃用（例如 ListView）时，MauiReactor 对应的封装实际上也已弃用。请使用替代控件的 MauiReactor 封装（例如 CollectionView）。
• 状态管理：使用 State<T> 和 Props<T>，不要使用过时示例中可能出现的旧式 RxComponent 模式。
• 导航：使用 MauiReactor 内置导航（Navigation.PushAsync<PageComponent>()），除非有意集成 Shell，否则不要混用 MAUI Shell 的 GoToAsync。

---

Blazor Hybrid 专属指导

• 使用 BlazorWebView（而不是旧版 WebView）来承载 Razor 组件。
• 使用 .NET 10 Razor 语法：@rendermode 指令、[SupplyParameterFromQuery] 以及最新的组件模型。
• JS 互操作：使用 IJSRuntime.InvokeAsync<T>()，不要使用已弃用的同步 IJSInProcessRuntime 移动端模式。
• 安全区域：在 Blazor Hybrid 中，使用 CSS env(safe-area-inset-*)；切勿在同一个元素上同时使用 XAML SafeAreaEdges 和 CSS 安全区域内边距（会导致内边距叠加）。
• Web 资源拦截：.NET 10 在 BlazorWebView 和 HybridWebView 上新增了 WebResourceRequested 事件，可用于拦截请求。

---

版本检测速查表

查看 TFM

TFM 模式	.NET 版本
net10.0-*	.NET 10（最新，当前版本）
net9.0-*	.NET 9
net8.0-*	.NET 8（LTS）

查看 MAUI SDK 版本

如果 .csproj 使用 <UseMaui>true</UseMaui>，则 MAUI 版本与 TFM 相对应：

• net10.0 → MAUI 10
• net9.0 → MAUI 9

查看 MauiReactor 版本

检查 <PackageReference Include="Reactor.Maui" Version="X.Y.Z" />：

• v3.x → 兼容 .NET MAUI 9/10，使用功能开关热重载
• v2.x → 旧版，使用 EnableMauiReactorHotReload() 构建器模式

查看 CommunityToolkit 版本

检查 <PackageReference Include="CommunityToolkit.Maui" Version="X.Y.Z" />：

• v11+ → 兼容 .NET 10
• v9-10 → 兼容 .NET 9
• v5-7 → 兼容 .NET 8

---

快速规则

1. 先阅读 .csproj。 不要在不了解目标框架的情况下生成代码。
2. 有疑问时，使用较新的 API。 如果有两种方式可以实现某项功能，较新的方式才是正确的。
3. 切勿使用 Xamarin.* 命名空间。 它们在 MAUI 中不存在。
4. 新项目中切勿使用 Compatibility.* 类型。 它们仅用于迁移。
5. 使用任何 Device.* API 前，先检查此表。 Device 类已完全弃用。
6. 在 .NET 10+ 中，动画、警报和操作表的方法名称使用 *Async。
7. 使用 API 前，先确认第三方包的版本——CommunityToolkit、MauiReactor 等包在主版本升级时可能会有破坏性变更。