ASP.NET 核心 Blazor Hybrid 路由和導覽

發行項
11/12/2024

注意

這不是這篇文章的最新版本。如需目前的版本，請參閱本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。如需詳細資訊，請參閱 .NET 和 .NET Core 支持原則。如需目前的版本，請參閱本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

如需目前的版本，請參閱本文的 .NET 9 版本。

本文會說明如何在 Blazor Hybrid 應用程式中管理要求路由和導覽。

URI 要求路由行為

預設 URI 要求路由行為:

如果應用程式的來源 URI 與要求 URI 之間符合主機名稱和結構描述，則連結是內部連結。當主機名稱和結構描述不相符或連結設定 target="_blank" 時，連結會被視爲外部連結。
如果連結是內部連結，應用程式會在 BlazorWebView 中開啟連結。
如果連結是外部連結，則連結會由裝置根據裝置為連結的結構描述註冊的處理常式所決定的應用程式來開啟。
對於由於 URI 的最後一個區段使用點標記法 (例如 /file.x，/Maryia.Melnyk，/image.gif)，但不指向任何靜態內容而看似要求檔案的內部連結:
- WPF 和 Windows Forms: 會傳回主機頁面內容。
- .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 的建構函式，該建構函式位於 MainPage.xaml.cs從專案範本建立的應用程式中.NET MAUI。

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 MAUI Blazor 混合式專案範本不是 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 程式碼檔案中，關閉按鈕會呼叫 PopAsync 的 CloseButton_Clicked 事件處理常式從瀏覽堆疊中關閉彈出 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 t推送至瀏覽堆疊。

下列範例是以 .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 核心 Blazor Hybrid 路由和導覽

URI 要求路由行為

取得或設定初始導覽的路徑

在頁面和 Razor 元件之間瀏覽

應用程式連結 (深層連結)

其他資源