ASP.NET 核心 Blazor 导航

本文介绍如何在Blazor中触发和处理页面导航。 虽然用户可以使用普通 HTML 链接在不同页面之间导航，但 Blazor 可以增强应用程序中的导航，以避免完整页面重载并提供更流畅的体验。 使用 NavLink 组件创建导航链接，当链接与当前页匹配时自动应用样式设置。 对于 C# 代码中的编程导航和 URI 管理，请使用 NavigationManager 该服务。

本文介绍如何在Blazor中触发和处理页面导航。 使用 NavLink 组件创建导航链接，当链接与当前页匹配时自动应用样式设置。 对于 C# 代码中的编程导航和 URI 管理，请使用 NavigationManager 该服务。

有两个 NavLinkMatch 选项可分配给 Match 元素的 <NavLink> 属性：

• NavLinkMatch.All：当 NavLink 与当前 URL 匹配时处于活动状态，忽略查询字符串和片段。 若要在查询字符串/片段中包含匹配，请使用 Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragmentAppContext 开关 设置为 true。
• NavLinkMatch.Prefix（默认）：当 NavLink 与当前 URL 的任何前缀匹配时处于活动状态。

若要采用自定义匹配逻辑，请创建 NavLink 的子类并重写其 ShouldMatch 方法。 如果要应用 true CSS 类，请从方法返回 active：

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        // Custom matching logic
    }
}

有两个 NavLinkMatch 选项可分配给 Match 元素的 <NavLink> 属性：

• NavLinkMatch.All：NavLink 与整个当前 URL（包括查询字符串和片段）匹配时处于活动状态。
• NavLinkMatch.Prefix（默认）：当 NavLink 与当前 URL 的任何前缀匹配时处于活动状态。

在静态服务器端呈现期间导航管理器重定向行为（静态 SSR）

对于静态服务器端呈现（静态 SSR）期间的重定向， NavigationManager 依赖于引发 NavigationException 框架捕获的重定向，该框架将错误转换为重定向。 调用后 NavigateTo 存在的代码未调用。 使用 Visual Studio 时，调试器会中断异常，因此当 Visual Studio UI 中处理 此异常类型时 ，需要取消选中“中断”复选框，以避免调试器停止将来重定向。

可以使用 <BlazorDisableThrowNavigationException> MSBuild 属性设置为 true 在应用的项目文件中选择加入不再引发 NavigationException。 此外，在调用 NavigateTo 后执行代码时，它之前不会运行。 在 .NET 10 或更高版本 Blazor Web App 的项目模板中默认启用此行为：

<BlazorDisableThrowNavigationException>true</BlazorDisableThrowNavigationException>

找不到响应

NavigationManager 提供了一种机制 NotFound，用于在静态服务器端渲染（静态 SSR）或全局交互式渲染过程中，处理请求资源未找到的情况。

• 静态 SSR：调用 NavigationManager.NotFound 会将 HTTP 状态代码设置为 404。

• 交互式呈现：向路由器（Blazor）发出Router信号以呈现“找不到”内容。

• 流式呈现：如果 增强的导航 处于活动状态，流式呈现将在找不到内容时无需重新加载页面。 当增强的导航被阻止时，框架会重定向到“找不到”内容，并刷新页面。

流式呈现只能呈现具有路由的组件，例如 NotFoundPage 分配（NotFoundPage="..."）或 状态代码页重新执行中间件页分配 （UseStatusCodePagesWithReExecute）。 DefaultNotFound 404 内容（“Not found”纯文本）没有路由，因此无法在流呈现期间使用。

NavigationManager.NotFound 内容渲染使用以下技术，无论响应是否已开始（按顺序）：

• 如果 NotFoundEventArgs.Path 已设置，则呈现已分配页面的内容。
• 如果 Router.NotFoundPage 已设置，则呈现分配的页面。
• 已配置的状态码页面重执行中间件页面。
• 如果没有采用上述任何方法，则不采取任何措施。

在处理浏览器地址路由问题（如 URL 输入错误或点击无效链接）时优先。

当组件以静态方式呈现（静态 SSR）并 NavigationManager.NotFound 调用时，将在响应上设置 404 状态代码：

@page "/render-not-found-ssr"
@inject NavigationManager Navigation

@code {
    protected override void OnInitialized()
    {
        Navigation.NotFound();
    }
}

要为全局交互式呈现提供“未找到”的内容，请使用“未找到”页（Razor 组件）。

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout

<h3>Not Found</h3>
<p>Sorry, the content you are looking for does not exist.</p>

该 NotFound 组件分配给路由器 NotFoundPage 的参数。 NotFoundPage 支持可跨状态代码页面重新执行中间件使用的路由，包括非 Blazor 中间件。

在以下示例中，上述 NotFound 组件存在于应用的 Pages 文件夹中，并传递给 NotFoundPage 参数：

<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
</Router>

使用全局交互式呈现模式渲染组件时，调用 NavigationManager.NotFound 来触发 Blazor 路由器渲染 NotFound 组件：

@page "/render-not-found-interactive"
@inject NavigationManager Navigation

@if (RendererInfo.IsInteractive)
{
    <button @onclick="TriggerNotFound">Trigger Not Found</button>
}

@code {
    private void TriggerNotFound()
    {
        Navigation.NotFound();
    }
}

当OnNotFound被调用时，可以使用NavigationManager.NotFound事件进行通知。 仅当调用 NavigationManager.NotFound 时事件才会触发，而不是对任意 404 响应都触发。 例如，将HttpContextAccessor.HttpContext.Response.StatusCode设置为404不会触发NavigationManager.NotFound/OnNotFound。

实现自定义路由器的应用也可以使用 NavigationManager.NotFound。 自定义路由器可以根据响应的状态呈现来自两个源的“找不到”内容：

• 无论响应状态如何，页面的重新执行路径都可以通过将其传递给 UseStatusCodePagesWithReExecute来使用。

  app.UseStatusCodePagesWithReExecute(
      "/not-found", createScopeForStatusCodePages: true);
  

• 响应启动之后，可以通过订阅路由器中的 NotFoundEventArgs.Path 来使用 OnNotFoundEvent。

  @code {
      [CascadingParameter]
      public HttpContext? HttpContext { get; set; }
  
      private void OnNotFoundEvent(object sender, NotFoundEventArgs e)
      {
          // Only execute the logic if HTTP response has started,
          // because setting NotFoundEventArgs.Path blocks re-execution
          if (HttpContext?.Response.HasStarted == false)
          {
              return;
          }
  
          var type = typeof(CustomNotFoundPage);
          var routeAttributes = type.GetCustomAttributes<RouteAttribute>(inherit: true);
  
          if (routeAttributes.Length == 0)
          {
              throw new InvalidOperationException($"The type {type.FullName} " +
                  $"doesn't have a {nameof(RouteAttribute)} applied.");
          }
  
          var routeAttribute = (RouteAttribute)routeAttributes[0];
  
          if (routeAttribute.Template != null)
          {
              e.Path = routeAttribute.Template;
          }
      }
  }
  

在下面的示例中，对于采用 交互式服务器端呈现（交互式 SSR）的组件，根据调用的位置 OnNotFound 呈现自定义内容。 如果在组件初始化上找不到电影时，以下 Movie 组件触发了该事件，则自定义消息指出找不到请求的电影。 如果事件是由 User 以下示例中的组件触发的，则不同的消息指出找不到用户。

以下 NotFoundContext 服务负责管理在组件找不到内容时的上下文和消息。

NotFoundContext.cs:

public class NotFoundContext
{
    public string? Heading { get; private set; }
    public string? Message { get; private set; }

    public void UpdateContext(string heading, string message)
    {
        Heading = heading;
        Message = message;
    }
}

该服务在服务器端 Program 文件中注册：

builder.Services.AddScoped<NotFoundContext>();

页面 NotFound 插入 NotFoundContext 并显示标题和消息。

Pages/NotFound.razor:

@page "/not-found"
@layout MainLayout
@inject NotFoundContext NotFoundContext

<h3>@NotFoundContext.Heading</h3>
<div>
    <p>@NotFoundContext.Message</p>
</div>

组件 Routes （Routes.razor） 通过NotFound参数将NotFoundPage组件设置为“未找到”页：

<Router AppAssembly="typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    ...
</Router>

在以下示例组件中：

• 将NotFoundContext服务和NavigationManager一起注入。
• 在 OnInitializedAsync 中，HandleNotFound 是分配给 OnNotFound 事件的事件处理程序。 HandleNotFound 调用 NotFoundContext.UpdateContext 为组件中 NotFound 找不到的内容设置标题和消息。
• 组件通常使用路由参数中的 ID 从数据存储（如数据库）获取电影或用户。 在以下示例中，不会返回任何实体（null）来模拟找不到实体时会发生什么情况。
• 当没有实体返回到 OnInitializedAsync 时， NavigationManager.NotFound 会被调用，从而触发 OnNotFound 事件和 HandleNotFound 事件处理程序。 路由程序显示“未找到”的内容。
• 在 HandleNotFound 中，IDisposable.Dispose 方法在组件处置中取消挂载。

Movie 组件 (Movie.razor)：

@page "/movie/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching movie is returned
    from the call to GetMovie().
</div>

@code {
    [Parameter]
    public int Id { get; set; }

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var movie = await GetMovie(Id);

        if (movie == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("Movie Not Found",
            "Sorry! The requested movie wasn't found.");
    }

    private async Task<MovieItem[]?> GetMovie(int id)
    {
        // Simulate no movie with matching id found
        return await Task.FromResult<MovieItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class MovieItem
    {
        public int Id { get; set; }
        public string? Title { get; set; }
    }
}

User 组件 (User.razor)：

@page "/user/{Id:int}"
@implements IDisposable
@inject NavigationManager NavigationManager
@inject NotFoundContext NotFoundContext

<div>
    No matter what ID is used, no matching user is returned
    from the call to GetUser().
</div>

@code {
    [Parameter]
    public int Id { get; set; }

    protected override async Task OnInitializedAsync()
    {
        NavigationManager.OnNotFound += HandleNotFound;

        var user = await GetUser(Id);

        if (user == null)
        {
            NavigationManager.NotFound();
        }
    }

    private void HandleNotFound(object? sender, NotFoundEventArgs e)
    {
        NotFoundContext.UpdateContext("User Not Found",
            "Sorry! The requested user wasn't found.");
    }

    private async Task<UserItem[]?> GetUser(int id)
    {
        // Simulate no user with matching id found
        return await Task.FromResult<UserItem[]?>(null);
    }

    void IDisposable.Dispose()
    {
        NavigationManager.OnNotFound -= HandleNotFound;
    }

    public class UserItem
    {
        public int Id { get; set; }
        public string? Name { get; set; }
    }
}

若要使用测试应用在本地演示中访问上述组件，请在组件（NavMenu）中创建条目NavMenu.razor以访问Movie这些组件和User组件。 以下示例中作为路由参数传入的实体 ID 是模拟值，不影响实际行为，因为组件并未使用这些值，而是模拟找不到电影或用户的场景。

在 NavMenu.razor中：

<div class="nav-item px-3">
    <NavLink class="nav-link" href="movie/1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Movie
    </NavLink>
</div>

<div class="nav-item px-3">
    <NavLink class="nav-link" href="user/2">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> User
    </NavLink>
</div>

增强的导航和表单处理

本部分适用于 Blazor Web Apps。

Blazor Web App 可为页面导航和表单处理请求提供两种路由：

• 普通导航（跨文档导航）：为请求 URL 触发整页重载。
• 增强型导航（同一文档导航）：Blazor 截获请求并改为执行 fetch 请求。 Blazor 然后将响应内容修补到页面的 DOM 中。 Blazor 的增强型导航和表单处理无需全页重载，并且会保留更多页面状态，因此页面加载速度更快，通常不会丢失用户在页面上的滚动位置。

增强型导航可用于以下情况：

• 使用 Blazor Web App 脚本 (blazor.web.js)，而不使用 Blazor Server 脚本 (blazor.server.js) 或 Blazor WebAssembly 脚本 (blazor.webassembly.js)。
• 该功能未显式禁用。
• 目标 URL 位于内部基 URI 空间（应用的基本路径）内，且链接指向该页面时未将 data-enhance-nav 属性设置为 false。

如果启用了服务器端路由和增强型导航，则仅针对从交互式运行时启动的编程导航调用位置更改处理程序。 在未来版本中，其他类型的导航（如跟随链接）也可能调用位置更改处理程序。

当出现增强型导航时，通常会调用向交互式服务器和 WebAssembly 运行时注册的 LocationChanged 事件处理程序。 在某些情况下，位置更改处理程序可能无法拦截增强型导航。 例如，用户可能在交互式运行时可用之前切换到另一个页面。 因此，应用逻辑不依赖于调用位置更改处理程序非常重要，因为无法保证处理程序的执行。

调用 NavigateTo 时：

• 如果 forceLoad 是 false，这是默认设置：
  • 而且当前 URL 中可使用增强型导航，Blazor 的增强型导航已激活。
  • 否则，Blazor 会对请求的 URL 执行整页重载。
• 如果 forceLoad 为 true：Blazor 会对请求的 URL 执行整页重载，无论增强型导航是否可用。

可以通过调用 NavigationManager.Refresh(bool forceLoad = false) 来刷新当前页，它会始终执行增强型导航（如果可用）。 如果增强型导航不可用，Blazor 将执行整页重载。

Navigation.Refresh();

将 true 传递给 forceLoad 参数以确保始终执行整页重载，即使增强的导航可用：

Navigation.Refresh(true);

默认启用增强型导航，但可使用 data-enhance-nav HTML 属性按每个链接进行分层控制。

以下示例禁用增强型导航：

<a href="redirect" data-enhance-nav="false">
    GET without enhanced navigation
</a>

<ul data-enhance-nav="false">
    <li>
        <a href="redirect">GET without enhanced navigation</a>
    </li>
    <li>
        <a href="redirect-2">GET without enhanced navigation</a>
    </li>
</ul>

如果目标为非 Blazor 终结点，则增强型导航不适用，客户端 JavaScript 会在完整页面加载时重试。 这可确保对于不应修补到现有页面中的外部页面，框架不会产生混淆。

若要启用增强的表单处理，请将 Enhance 参数添加到 EditForm 表单或将 data-enhance 属性添加到 HTML 表单（<form>）：

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

增强的表单处理不是分层的，也不会传输到子表单：

❌ 不支持：无法在上级元素上设置增强型导航来为表单启用增强型导航。

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

增强型表单发布仅适用于 Blazor 终结点。 将增强型表单提交到非 Blazor 终结点会导致错误。

若要禁用增强型导航，请执行以下操作：

• 对于 EditForm，请从表单元素中移除 Enhance 参数（或将其设置为 false：Enhance="false"）。
• 对于 HTML <form>，请从表单元素中移除 data-enhance 特性（或将其设置为 false：data-enhance="false"）。

如果更新后的内容不是服务器呈现的一部分，Blazor 的增强型导航和表单处理可能会撤消对 DOM 的动态更改。 若要保留元素的内容，请使用 data-permanent 特性。

在以下示例中，当页面加载时，<div> 元素的内容由脚本动态更新：

<div data-permanent>
    ...
</div>

在客户端上启动 Blazor 后，可使用 enhancedload 事件监听增强的页面更新。 这允许将更改重新应用于可能已通过增强的页面更新撤消的 DOM。

Blazor.addEventListener('enhancedload', () => console.log('Enhanced update!'));

若要全局禁用增强的导航和表单处理，请参阅 ASP.NET Core Blazor 启动。

加载 JavaScript 时，需要特别注意采用静态服务器端呈现（静态 SSR）的增强型导航。 有关详细信息，请参阅 ASP.NET Core Blazor JavaScript 及静态服务器端呈现（静态 SSR）。

导航历史记录状态

NavigationManager 使用浏览器的历史记录 API 来维护与应用程序所做的每个位置更改相关的导航历史记录状态。 维护历史状态在外部重定向场景中特别有用，例如 使用外部标识提供者对用户进行身份验证时。 有关详细信息，请参阅导航选项部分。

导航选项

将 NavigationOptions 传递给 NavigateTo 以控制以下行为：

• ForceLoad：绕过客户端路由并强制浏览器从服务器加载新页面，无论 URI 是否由客户端路由器处理。 默认值为 false。
• ReplaceHistoryEntry：替换历史记录堆栈中的当前条目。 如果为 false，则将新条目附加到历史记录堆栈。 默认值为 false。
• HistoryEntryState：获取或设置要附加到历史记录条目的状态。

Navigation.NavigateTo("/path", new NavigationOptions
{
    HistoryEntryState = "Navigation state"
});

有关在处理位置更改时获取与目标历史记录条目关联的状态的详细信息，请参阅处理/防止位置更改部分。

使用 [SupplyParameterFromQuery] 属性指定组件参数来自查询字符串。

将 [SupplyParameterFromQuery] 属性与 [Parameter] 属性结合使用，指定可路由组件的组件参数可以来自查询字符串。

查询字符串提供的组件参数支持以下类型：

• bool、DateTime、decimal、double、float、Guid、int、long、string。
• 上述类型的可为空变体。
• 上述类型的数组，无论它们是可为空还是不可为空。

正确的与文化无关的格式设置适用于给定类型 (CultureInfo.InvariantCulture)。

指定 [SupplyParameterFromQuery] 属性的 Name 属性以使用不同于组件参数名称的查询参数名称。 在以下示例中，组件参数的 C# 名称是 {COMPONENT PARAMETER NAME}。 为 {QUERY PARAMETER NAME} 占位符指定了不同的查询参数名称：

与组件参数属性 ([Parameter]) 不同，[SupplyParameterFromQuery] 属性除了可以标记为 private 外，还可以标记为 public。

[SupplyParameterFromQuery(Name = "{QUERY PARAMETER NAME}")]
private string? {COMPONENT PARAMETER NAME} { get; set; }

与组件参数属性 ([Parameter]) 一样，[SupplyParameterFromQuery] 属性始终是 .NET 6/7 中的 public 属性。 在 .NET 8 或更高版本中，[SupplyParameterFromQuery] 属性可以标记为 public或 private。

[Parameter]
[SupplyParameterFromQuery(Name = "{QUERY PARAMETER NAME}")]
public string? {COMPONENT PARAMETER NAME} { get; set; }

以下示例中使用的 URL 为 /search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman:

• Filter 属性解析为 scifi stars。
• Page 属性解析为 3。
• Stars 数组是从名为 star (Name = "star") 的查询参数填充的，并解析为 LeVar Burton 和 Gary Oldman。

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

@if (Stars is not null)
{
    <p>Stars:</p>

    <ul>
        @foreach (var name in Stars)
        {
            <li>@name</li>
        }
    </ul>
}

@code {
    [SupplyParameterFromQuery]
    private string? Filter { get; set; }

    [SupplyParameterFromQuery]
    private int? Page { get; set; }

    [SupplyParameterFromQuery(Name = "star")]
    private string[]? Stars { get; set; }
}

Search.razor:

@page "/search"

<h1>Search Example</h1>

<p>Filter: @Filter</p>

<p>Page: @Page</p>

@if (Stars is not null)
{
    <p>Stars:</p>

    <ul>
        @foreach (var name in Stars)
        {
            <li>@name</li>
        }
    </ul>
}

@code {
    [Parameter]
    [SupplyParameterFromQuery]
    public string? Filter { get; set; }

    [Parameter]
    [SupplyParameterFromQuery]
    public int? Page { get; set; }

    [Parameter]
    [SupplyParameterFromQuery(Name = "star")]
    public string[]? Stars { get; set; }
}

使用 GetUriWithQueryParameter 在当前 URL 上添加、更改或删除一个或多个查询参数：

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameter("{NAME}", {VALUE})

在上面的示例中：

• {NAME} 占位符指定查询参数名称。 {VALUE} 占位符将值指定为支持的类型。 本节后面的内容列出了支持的类型。
• 返回的字符串相当于包含单个参数的当前 URL：
  • 如果查询参数名称在当前 URL 中不存在，则进行添加。
  • 如果查询参数存在于当前 URL 中，则更新为提供的值。
  • 如果所提供值的类型是可空且值为null，则将其删除。
• 正确的与文化无关的格式设置适用于给定类型 (CultureInfo.InvariantCulture)。
• 查询参数名称和值是 URL 编码的。
• 如果存在类型的多个实例，则所有具有匹配查询参数名称的值都会被替换。

调用 GetUriWithQueryParameters 以创建从 Uri 构造的 URI（添加、更新或删除多个参数）。 对于每个值，框架使用 value?.GetType() 来确定每个查询参数的运行时类型，并选择正确的与文化无关的格式设置。 对于不支持的类型，框架将引发错误。

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

{PARAMETERS} 占位符是一个 IReadOnlyDictionary<string, object>。

向 GetUriWithQueryParameters 传递 URI 字符串，以从提供的 URI 生成新的 URI（添加、更新或删除多个参数）。 对于每个值，框架使用 value?.GetType() 来确定每个查询参数的运行时类型，并选择正确的与文化无关的格式设置。 对于不支持的类型，框架将引发错误。 本节后面的内容列出了支持的类型。

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters("{URI}", {PARAMETERS})

• {URI} 占位符是带或不带查询字符串的 URI。
• {PARAMETERS} 占位符是一个 IReadOnlyDictionary<string, object>。

支持的类型与路由约束的支持类型相同：

• bool
• DateOnly
• DateTime
• decimal
• double
• float
• Guid
• int
• long
• string
• TimeOnly

支持的类型包括：

• 上述类型的可为空变体。
• 上述类型的数组，无论它们是可为空还是不可为空。

如果参数存在，则替换查询参数值

Navigation.GetUriWithQueryParameter("full name", "Morena Baccarin")

如果参数不存在，则追加查询参数和值

Navigation.GetUriWithQueryParameter("name", "Morena Baccarin")

如果参数值为 null，则删除查询参数

Navigation.GetUriWithQueryParameter("full name", (string)null)

添加、更新和删除查询参数

在下面的示例中：

• 删除了 name（如果存在）。
• 向 age 添加了值 25 (int)（如果不存在）。 如果存在，age 的值已更新为 25。
• 添加了 eye color 或为其更新了值 green。

Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["name"] = null,
        ["age"] = (int?)25,
        ["eye color"] = "green"
    })

支持可枚举值

在下面的示例中：

• 添加了 full name 或将其更新为 Morena Baccarin（单个值）。
• 添加了 ping 参数或将其替换为 35、16、87 和 240。

Navigation.GetUriWithQueryParameters(
    new Dictionary<string, object?>
    {
        ["full name"] = "Morena Baccarin",
        ["ping"] = new int?[] { 35, 16, null, 87, 240 }
    })

使用添加或修改的查询字符串进行导航

若要使用添加或修改的查询字符串进行导航，请将生成的 URL 传递给 NavigateTo。

下面的示例调用：

• GetUriWithQueryParameter 以使用值 name 添加或替换 Morena Baccarin 查询参数。
• 调用 NavigateTo 以触发导航到新 URL。

Navigation.NavigateTo(
    Navigation.GetUriWithQueryParameter("name", "Morena Baccarin"));

可从 NavigationManager.Uri 属性中获取请求的查询字符串：

@inject NavigationManager Navigation

...

var query = new Uri(Navigation.Uri).Query;

若要解析查询字符串的参数，一种方法是使用URLSearchParams以及JavaScript (JS) 的互操作：

export createQueryString = (string queryString) => new URLSearchParams(queryString);

有关使用 JavaScript 模块进行 JavaScript 隔离的详细信息，请参阅在 ASP.NET Core Blazor 中从 .NET 方法调用 JavaScript 函数。

导航至命名的元素

使用以下方法，通过对命名元素的哈希处理 (#) 引用，导航到该元素。 对组件中的元素路由，以及对外部组件中的元素路由，均使用根相对路径。 前导正斜杠 (/) 是可选的。

以下每种方法的示例均演示了如何导航到 id 组件中 targetElement 为 Counter 的元素：

• 带 <a> 的 Anchor 元素 (href)：

  <a href="/counter#targetElement">
  

• 带 NavLink 的 href 组件：

  <NavLink href="/counter#targetElement">
  

• NavigationManager.NavigateTo 传递相对 URL：

  Navigation.NavigateTo("/counter#targetElement");
  

以下示例演示如何导航到组件和外部组件中命名的 H2 标题。

在 Home (Home.razor) 和 Counter (Counter.razor) 组件中，将以下标记置于现有组件标记的底部，以用作导航目标。 <div> 创建人工垂直空间来演示浏览器滚动行为：

<div class="border border-info rounded bg-info" style="height:500px"></div>

<h2 id="targetElement">Target H2 heading</h2>
<p>Content!</p>

向应用添加以下 FragmentRouting 组件。

FragmentRouting.razor:

@page "/fragment-routing"
@inject NavigationManager Navigation

<PageTitle>Fragment routing</PageTitle>

<h1>Fragment routing to named elements</h1>

<ul>
    <li>
        <a href="/fragment-routing#targetElement">
            Anchor in this component
        </a>
    </li>
    <li>
        <a href="/#targetElement">
            Anchor to the <code>Home</code> component
        </a>
    </li>
    <li>
        <a href="/counter#targetElement">
            Anchor to the <code>Counter</code> component
        </a>
    </li>
    <li>
        <NavLink href="/fragment-routing#targetElement">
            Use a `NavLink` component in this component
        </NavLink>
    </li>
    <li>
        <button @onclick="NavigateToElement">
            Navigate with <code>NavigationManager</code> to the 
            <code>Counter</code> component
        </button>
    </li>
</ul>

<div class="border border-info rounded bg-info" style="height:500px"></div>

<h2 id="targetElement">Target H2 heading</h2>
<p>Content!</p>

@code {
    private void NavigateToElement()
    {
        Navigation.NavigateTo("/counter#targetElement");
    }
}

处理/阻止位置更改

RegisterLocationChangingHandler 注册一个处理程序来处理传入的导航事件。 LocationChangingContext 提供的处理程序上下文包括以下属性：

• TargetLocation：获取目标位置。
• HistoryEntryState：获取与目标历史记录条目关联的状态。
• IsNavigationIntercepted：获取是否从链接截获了导航。
• CancellationToken：通过获取 CancellationToken 来判断导航是否被取消，例如，判断用户是否触发了不同的导航。
• PreventNavigation：调用以阻止导航过程的继续。

一个组件可以在 OnAfterRender{Async} 生命周期方法中注册多个位置更改处理程序。 导航调用在整个应用（跨多个组件）中注册的所有位置更改处理程序，并且任何内部导航都并行执行它们。 除了调用 NavigateTo 处理程序之外：

• 选择内部链接时，这些链接指向应用基路径下的 URL。
• 在浏览器中使用前进和后退按钮进行导航时。

处理程序仅针对应用中的内部导航执行。 如果用户选择导航到另一个站点的链接或手动将地址栏更改为另一个站点，则不会执行位置更改处理程序。

实现 IDisposable 并释放已注册的处理程序以取消注册它们。 有关详细信息，请参阅 ASP.NET Core Razor 组件处置。

在以下示例中，为导航事件注册了位置更改处理程序。

NavHandler.razor:

@page "/nav-handler"
@implements IDisposable
@inject NavigationManager Navigation

<p>
    <button @onclick="@(() => Navigation.NavigateTo("/"))">
        Home (Allowed)
    </button>
    <button @onclick="@(() => Navigation.NavigateTo("/counter"))">
        Counter (Prevented)
    </button>
</p>

@code {
    private IDisposable? registration;

    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender)
        {
            registration = 
                Navigation.RegisterLocationChangingHandler(OnLocationChanging);
        }
    }

    private ValueTask OnLocationChanging(LocationChangingContext context)
    {
        if (context.TargetLocation == "/counter")
        {
            context.PreventNavigation();
        }

        return ValueTask.CompletedTask;
    }

    public void Dispose() => registration?.Dispose();
}

由于可以异步取消内部导航，因此可能会出现对已注册处理程序的多个重叠调用。 例如，当用户快速选择页面上的后退按钮或在执行导航之前选择多个链接时，可能会发生多个处理程序调用。 下面是异步导航逻辑的摘要：

• 如果注册了任何位置更改处理程序，则所有导航最初都将还原，如果导航没有取消，则会重播。
• 如果发出重叠的导航请求，则最新的请求始终会取消先前的请求，这意味着：
  • 应用可将多个后退和前进按钮选择视为单个选择。
  • 如果用户在导航完成之前选择了多个链接，则最后选择的链接决定该导航。

有关将 NavigationOptions 传递到 NavigateTo 以控制导航历史记录堆栈的条目和状态的详细信息，请参阅导航选项部分。

有关其他示例代码，请参阅 NavigationManagerComponent（BasicTestApp 参考源）中的 dotnet/aspnetcore。

只要呈现导航事件，NavigationLock 组件就会将其拦截，除非决定继续或取消，否则将一直有效“锁定”任何给定的导航。 当导航拦截的范围可以限定为组件的生存期时，使用 NavigationLock。

NavigationLock 参数：

• ConfirmExternalNavigation 设置浏览器对话框以提示用户确认或取消外部导航。 默认值为 false。 显示确认对话框需要在使用浏览器地址栏中的 URL 触发外部导航之前与页面进行初始用户交互。 有关交互要求的详细信息，请参阅 Window： beforeunload 事件。
• OnBeforeInternalNavigation 为内部导航事件设置回调。

在下面的 NavLock 组件中：

• 在成功导航到 https://www.microsoft.com 之前，用户必须尝试确认过 Microsoft 网站的链接可访问。
• 如果用户拒绝通过生成 PreventNavigation。

NavLock.razor:

@page "/nav-lock"
@inject IJSRuntime JSRuntime
@inject NavigationManager Navigation

<NavigationLock ConfirmExternalNavigation="true" 
    OnBeforeInternalNavigation="OnBeforeInternalNavigation" />

<p>
    <button @onclick="Navigate">Navigate</button>
</p>

<p>
    <a href="https://www.microsoft.com">Microsoft homepage</a>
</p>

@code {
    private void Navigate()
    {
        Navigation.NavigateTo("/");
    }

    private async Task OnBeforeInternalNavigation(LocationChangingContext context)
    {
        var isConfirmed = await JSRuntime.InvokeAsync<bool>("confirm", 
            "Are you sure you want to navigate to the root page?");

        if (!isConfirmed)
        {
            context.PreventNavigation();
        }
    }
}

有关其他示例代码，请参阅 ConfigurableNavigationLock（BasicTestApp 参考源）中的 dotnet/aspnetcore 组件。

有关示例应用中上述代码的演示，请获取 Blazor Web App 或 Blazor WebAssembly 示例应用。