ASP.NET Core Blazor Hybrid 路由和导航

项目
11/06/2024

注意

此版本不是本文的最新版本。对于当前版本，请参阅此文的 .NET 8 版本。

警告

此版本的 ASP.NET Core 不再受支持。有关详细信息，请参阅 .NET 和 .NET Core 支持策略。对于当前版本，请参阅此文的 .NET 8 版本。

重要

此信息与预发布产品相关，相应产品在商业发布之前可能会进行重大修改。 Microsoft 对此处提供的信息不提供任何明示或暗示的保证。

对于当前版本，请参阅此文的 .NET 8 版本。

本文介绍如何管理 Blazor Hybrid 应用中的请求路由和导航。

URI 请求路由行为

默认 URI 请求路由行为：

如果应用程序的原始 URI 和请求 URI 之间的主机名和方案匹配，则链接是内部链接。如果主机名和方案不匹配或链接设置为 target="_blank"，则链接被视为外部链接。
如果链接是内部链接，则链接由应用在 BlazorWebView 中打开。
如果链接是外部链接，则链接由设备根据设备为链接方案注册的处理程序确定的应用打开。
对于由于 URI 的最后一段使用点表示法（例如 /file.x、/Maryia.Melnyk、/image.gif）但不指向任何静态内容而看似请求文件的内部链接：
- WPF 和 Windows 窗体：返回主机页面内容。
- .NET MAUI：返回 404 响应。

若要更改未设置 target="_blank" 的链接的链接处理行为，请注册 UrlLoading 事件并设置 UrlLoadingEventArgs.UrlLoadingStrategy 属性。 UrlLoadingStrategy 枚举允许将链接处理行为设置为以下任何值：

OpenExternally：使用设备确定的应用加载 URL。这是具有外部主机的 URI 的默认策略。
OpenInWebView：在 BlazorWebView 中加载 URL。这是具有与应用源匹配的主机的 URL 的默认策略。请勿将此策略用于外部链接，除非可以确保目标 URI 完全受信任。
CancelLoad：取消当前 URL 加载尝试。

UrlLoadingEventArgs.Url 属性用于获取或动态设置 URL。

警告

外部链接在设备确定的应用中打开。在 BlazorWebView 中打开外部链接可能会引入安全漏洞，除非可以确保外部链接完全受信任，否则不应启用。

API 文档：

以下示例需要 Microsoft.AspNetCore.Components.WebView 命名空间：

using Microsoft.AspNetCore.Components.WebView;

将以下事件处理程序添加到创建 BlazorWebView 的 Page 构造函数中，该构造函数是从 .NET MAUI 项目模板创建的应用中的 MainPage.xaml.cs。

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

将 UrlLoading="Handle_UrlLoading" 特性添加到 .xaml 文件中的 BlazorWebView 控件：

<blazor:BlazorWebView HostPage="wwwroot\index.html" 
    Services="{StaticResource services}" 
    x:Name="blazorWebView" 
    UrlLoading="Handle_UrlLoading">

在 .xaml.cs 文件中添加事件处理程序：

private void Handle_UrlLoading(object sender, 
    UrlLoadingEventArgs urlLoadingEventArgs)
{
    if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
    {
        urlLoadingEventArgs.UrlLoadingStrategy = 
            UrlLoadingStrategy.OpenInWebView;
    }
}

在包含 BlazorWebView 控件的窗体的构造函数中，添加以下事件注册：

blazorWebView.UrlLoading += 
    (sender, urlLoadingEventArgs) =>
    {
        if (urlLoadingEventArgs.Url.Host != "0.0.0.0")
        {
            urlLoadingEventArgs.UrlLoadingStrategy = 
                UrlLoadingStrategy.OpenInWebView;
        }
    };

当 Razor 组件完成加载时，使用 BlazorWebView.StartPath 属性获取或设置 Blazor 导航上下文中初始导航的路径。默认起始路径是相对根 URL 路径 (/)。

在 MainPage XAML 标记 (MainPage.xaml) 中，指定起始路径。以下示例将路径设置为 /welcome 处的欢迎页：

<BlazorWebView ... StartPath="/welcome" ...>
    ...
<BlazorWebView>

或者，可以在 MainPage 构造函数（MainPage.xaml.cs）中设置起始路径：

blazorWebView.StartPath = "/welcome";

在 MainWindow 设计器 (MainWindow.xaml) 中，指定起始路径。以下示例将路径设置为 /welcome 处的欢迎页：

<blazor:BlazorWebView ... StartPath="/welcome" ...>
    ...
</blazor:BlazorWebView>

在 Form1.cs 文件的 Form1 构造函数中，指定起始路径。以下示例将路径设置为 /welcome 处的欢迎页：

blazorWebView1.StartPath = "/welcome";

本部分介绍如何在 .NET MAUI 内容页和 Razor 组件之间导航。

.NET MAUIBlazor 混合项目模板不是基于 Shell 的应用，因此基于 Shell 的应用的基于 URI 的导航不适用于基于项目模板的项目。本部分内容中的示例使用 NavigationPage 来执行无模式或模式导航。

如下示例中：

应用的命名空间为 MauiBlazor，它与生成 .NET MAUIBlazor Hybrid 应用教程的建议项目名称一致。
ContentPage 放置在添加到名为 Views 的应用的一个新文件夹中。

在 App.xaml.cs 中，通过以下更改创建 MainPage 作为 NavigationPage：

- MainPage = new MainPage();
+ MainPage = new NavigationPage(new MainPage());

Views/NavigationExample.xaml：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:MauiBlazor"
             x:Class="MauiBlazor.Views.NavigationExample"
             Title="Navigation Example"
             BackgroundColor="{DynamicResource PageBackgroundColor}">
    <StackLayout>
        <Label Text="Navigation Example"
               VerticalOptions="Center"
               HorizontalOptions="Center"
               FontSize="24" />
        <Button x:Name="CloseButton" 
                Clicked="CloseButton_Clicked" 
                Text="Close" />
    </StackLayout>
</ContentPage>

在以下 NavigationExample 代码文件中，关闭按钮的 CloseButton_Clicked 事件处理程序调用 PopAsync 以使 ContentPage 从导航堆栈中弹出。

Views/NavigationExample.xaml.cs：

namespace MauiBlazor.Views;

public partial class NavigationExample : ContentPage
{
    public NavigationExample()
    {
        InitializeComponent();
    }

    private async void CloseButton_Clicked(object sender, EventArgs e)
    {
        await Navigation.PopAsync();
    }
}

在 Razor 组件中：

为应用的内容页添加命名空间。在下面的示例中，命名空间为 MauiBlazor.Views。
使用 @onclick 事件处理程序添加 HTML button 元素以打开内容页。事件处理程序方法名为 OpenPage。
在事件处理程序中，调用 PushAsync 以将 ContentPage（即NavigationExample）推送到导航堆栈上。

下面的示例基于 .NET MAUIBlazor 项目模板中的 Index 组件。

Pages/Index.razor：

@page "/"
@using MauiBlazor.Views

<h1>Hello, world!</h1>

Welcome to your new app.

<SurveyPrompt Title="How is Blazor working for you?" />

<button class="btn btn-primary" @onclick="OpenPage">Open</button>

@code {
    private async void OpenPage()
    {
        await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
    }
}

将前面的示例更改为模式导航：

在 CloseButton_Clicked 方法 (Views/NavigationExample.xaml.cs) 中，将 PopAsync 更改为 PopModalAsync：
```
- await Navigation.PopAsync();
+ await Navigation.PopModalAsync();
```

在 OpenPage 方法 (Pages/Index.razor) 中，将 PushAsync 更改为 PushModalAsync：

- await App.Current.MainPage.Navigation.PushAsync(new NavigationExample());
+ await App.Current.MainPage.Navigation.PushModalAsync(new NavigationExample());

有关详细信息，请参阅以下资源：

应用链接（深层链接）

通常需要连接网站和移动应用，以便网站上的链接能够启动移动应用并在移动应用中显示内容。应用链接（也称为深层链接）是一种技术，使移动设备能够响应 URI，并在由 URI 表示的移动应用中启动内容。

有关详细信息，请参阅 .NET MAUI 文档中的以下文章：

通过

ASP.NET Core Blazor Hybrid 路由和导航

URI 请求路由行为

获取或设置初始导航的路径

页面和 Razor 组件之间的导航

应用链接（深层链接）

其他资源