.NET MAUI 页面导航开发指南
任务概述
本任务目标是掌握在 .NET MAUI 应用中实现页面跳转（导航）的核心方法，包括使用 Shell 导航和 Navigation 栈管理两种主流方式。你将学会如何从主页跳转到详情页、传递参数、返回上一页，并理解不同导航模式的适用场景。
分步指南
1. 创建基础页面结构
首先创建两个页面：MainPage.xaml（起始页）和 DetailPage.xaml（目标页）。
关键代码（MainPage.xaml）
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MyApp.MainPage"
Title="主页">
<VerticalStackLayout Padding="20" Spacing="20">
<Label Text="欢迎来到主页！" FontSize="24" HorizontalOptions="Center" />
<Button Text="跳转到详情页"
Clicked="OnNavigateToDetailClicked"
HorizontalOptions="Center" />
</VerticalStackLayout>
</ContentPage>
关键代码（DetailPage.xaml）
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MyApp.DetailPage"
Title="详情页">
<VerticalStackLayout Padding="20" Spacing="20">
<Label x:Name="MessageLabel" FontSize="18" />
<Button Text="返回主页"
Clicked="OnGoBackClicked"
HorizontalOptions="Center" />
</VerticalStackLayout>
</ContentPage>
注意事项：
- 确保两个页面都已在
App.xaml.cs 中注册（若使用传统导航）。
Title 属性将显示在导航栏（如果启用）。
2. 实现传统页面导航（Navigation Stack）
使用 Navigation.PushAsync() 和 PopAsync() 实现页面入栈与出栈。
关键代码（MainPage.xaml.cs）
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
// 跳转到详情页（入栈）
await Navigation.PushAsync(new DetailPage());
}
关键代码（DetailPage.xaml.cs）
public partial class DetailPage : ContentPage
{
public DetailPage()
{
InitializeComponent();
MessageLabel.Text = "这是通过传统导航打开的页面。";
}
private async void OnGoBackClicked(object sender, EventArgs e)
{
// 返回上一页（出栈）
await Navigation.PopAsync();
}
}
注意事项：
- 传统导航要求起始页面必须是
NavigationPage 的根页面。
- 在
App.xaml.cs 中初始化时需包装：
MainPage = new NavigationPage(new MainPage());
3. 使用 Shell 导航（推荐方式）
Shell 提供更现代、声明式的导航体验，支持 URI 路由和参数传递。
关键代码（AppShell.xaml）
<?xml version="1.0" encoding="utf-8" ?>
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:local="clr-namespace:MyApp"
x:Class="MyApp.AppShell">
<!-- 注册路由 -->
<ShellContent Title="主页" ContentTemplate="{DataTemplate local:MainPage}" Route="main" />
<ShellContent ContentTemplate="{DataTemplate local:DetailPage}" Route="detail" />
</Shell>
关键代码（MainPage.xaml.cs - Shell 跳转）
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
// 使用 Shell.Current.GoToAsync 跳转
await Shell.Current.GoToAsync("//detail");
}
关键代码（DetailPage.xaml.cs - Shell 返回）
private async void OnGoBackClicked(object sender, EventArgs e)
{
// Shell 自动维护导航栈，返回上一页
await Shell.Current.GoToAsync("..");
}
注意事项：
- Shell 导航无需手动包装
NavigationPage。
- 使用
// 表示绝对路径，避免嵌套路由问题。
.. 表示返回上一级，适用于大多数场景。
4. 页面间传递参数
通过 Shell 路由传递简单参数（如 ID 或名称）。
关键代码（MainPage.xaml.cs - 传递参数）
private async void OnNavigateToDetailClicked(object sender, EventArgs e)
{
// 传递参数 user=张三
await Shell.Current.GoToAsync("detail?name=张三");
}
关键代码（DetailPage.xaml.cs - 接收参数）
[QueryProperty(nameof(Name), "name")]
public partial class DetailPage : ContentPage
{
private string name;
public string Name
{
get => name;
set
{
name = value;
OnPropertyChanged(); // 支持数据绑定更新
}
}
protected override void OnNavigatedTo(NavigatedToEventArgs args)
{
base.OnNavigatedTo(args);
MessageLabel.Text = $"你好，{Name}！";
}
}
注意事项：
- 必须使用
[QueryProperty] 特性绑定查询参数。
- 参数名必须与 URI 中的键名一致（如
name）。
- 复杂对象应序列化为 JSON 字符串或使用全局服务传递。
完整示例
App.xaml.cs
public partial class App : Application
{
public App()
{
InitializeComponent();
MainPage = new AppShell(); // 使用 Shell 作为主页面
}
}
AppShell.xaml.cs
public partial class AppShell : Shell
{
public AppShell()
{
InitializeComponent();
}
}
其余页面代码如上所示。此结构支持跨平台（iOS/Android/Windows/macOS）一致导航体验。
常见问题
-
问题：点击按钮无反应，页面未跳转
原因：未将起始页包装在 NavigationPage 中（传统导航），或未在 AppShell 中注册路由（Shell 导航）。
解决：
- 传统导航：
MainPage = new NavigationPage(new MainPage());
- Shell 导航：确保
AppShell.xaml 中包含 <ShellContent Route="xxx" ... />
-
问题：Shell 导航后无法返回，或返回到错误页面
原因：使用了相对路径（如 "detail"）而非绝对路径（"//detail"），导致路由嵌套。
解决：跳转到新“层级”时使用 // 前缀清除当前栈，例如 await Shell.Current.GoToAsync("//detail");
-
问题：传递的参数在 DetailPage 中为 null
原因：未正确使用 [QueryProperty]，或属性未触发 UI 更新。
解决：确保属性有 set 逻辑，并在 OnNavigatedTo 中使用值；属性名与 URI 参数名严格一致。
