17370845950

.NET MAUI是微软推出的原生跨平台UI框架，用C#和XAML一套代码编译为Android、iOS、Windows、macOS的原生控件；需dotnet 8.0+、安装maui workload，首屏由App.xaml.cs中MainPage=...指定，导航需NavigationPage或AppShell支持，热重载仅限部分XAML变更。

.NET MAUI 就是微软推出的、用 C# 和 XAML 写一套代码就能跑在 Android、iOS、Windows、macOS 四个平台上的原生跨平台 UI 框架——它不是“模拟器”或“WebView 壳”，而是把你的 Button、Label、ListView 等控件，实时翻译成各平台真正的原生控件（比如 iOS 的 UIButton、Windows 的 WinUI Button），所以性能和体验接近原生。

它不是 Xamarin.Forms 的“升级补丁”，而是重写：控件层全换、渲染路径更短、项目结构彻底扁平化（单项目，不再有 .iOS/.Android 多项目嵌套）。

---

怎么快速验证自己环境能跑起来

别急着建项目，先确认基础链路通不通：

dotnet --version
# 必须 ≥ 8.0（推荐 9.0，2025 年底已稳定）
dotnet workload list | findstr maui
# 应看到类似：maui, maui-android, maui-ios, maui-windows...
dotnet new maui -n TestApp && cd TestApp && dotnet build

如果 dotnet build 报错说缺 workload，就立刻补：

dotnet workload install maui

常见坑：Visual Studio 2025 17.8+ 安装时没勾选「.NET Multi-platform App UI 开发」——这会导致命令行能装 workload，但 VS 里新建项目模板不出现。必须重进 VS Installer → 修改 → 勾上它，再重启 VS。

---

创建第一个可运行的页面，关键三处不能漏

新建项目后，真正让 App

启动并显示内容，靠的是这三个文件协同：

• App.xaml：定义全局资源字典（比如主题色、字体），它本身不决定“哪个页面先显示”
• App.xaml.cs：里面 public partial class App : Application 类，它的构造函数里有一句关键代码：

  public App()
  {
      InitializeComponent();
      MainPage = new AppShell(); // ← 这行决定了首屏！
  }
  

• MainPage.xaml（或 AppShell.xaml）：实际渲染的根页面。如果你删了 AppShell 改用 MainPage，就得同步改 MainPage = new MainPage()

常见错误现象：

• 启动黑屏 / 白屏 → 检查 MainPage = ... 是否被注释或指向 null
• 编译通过但 Windows 上报错 “WinUI 3 runtime not found” → 需在 Windows 设置中开启「开发者模式」（设置 → 系统 → 针对开发人员 → 开启）

---

导航跳转为什么点不动？Navigation.PushAsync 失效的典型原因

Navigation.PushAsync(new DetailPage()) 不生效，90% 是因为当前页面根本不在导航栈里。

MAUI 要求：只有从 NavigationPage 包裹的页面出发，才能用 Navigation 属性跳转。

正确做法（两种）：

• 方式一（推荐）：在 App.xaml.cs 中这样设：

  MainPage = new NavigationPage(new MainPage());
  

• 方式二：用 AppShell（默认模板就是它），它内部自带导航容器，你只需确保跳转代码写在继承自 ContentPage 的页面里，且调用时上下文是有效的页面实例（比如在按钮点击事件里）。

容易忽略的细节：

• 在 App.OnStart() 或静态方法里直接调用 Navigation.PushAsync → 会抛 NullReferenceException，因为此时没有当前页面上下文
• 使用 Shell.Current.GoToAsync("//detail") 是另一套路由系统，和 Navigation 不互通，混用会迷路

---

热重载（Hot Reload）为什么改了 XAML 没反应？

热重载不是万能的，它只对以下修改实时生效：

• Text、BackgroundColor、FontSize 等属性值变更
• 添加/删除简单控件（如加一个 Label）

但以下情况必须重新编译：

• 修改 ViewModel 的属性或绑定逻辑
• 更改页面继承关系（比如把 ContentPage 改成 TabbedPage）
• 动态加载资源（如通过 ResourceManager 切语言）

另外：Windows 上热重载默认只对 WinUI 生效；Android/iOS 模拟器需确保启用「Hot Reload on File Save」并在调试状态下运行（F5 启动，不是 Ctrl+F5）。

最常被卡住的一点：改完 MainPage.xaml 后保存，但当前正在看的是 DetailPage ——热重载只刷新当前激活页面，不会自动跳回去。