Маршрутизация ASP.NET Core Blazor и навигация

Статическая и интерактивная маршрутизация

Этот раздел относится к Blazor Web Apps.

Если предварительная отрисовка включена, Blazor маршрутизатор (Routerкомпонент) Routes.razor<Router> выполняет статическую маршрутизацию компонентов во время отрисовки на стороне статического сервера (статический SSR). Этот тип маршрутизации называется статической маршрутизацией.

Когда компоненту назначен Routes режим интерактивной отрисовки, Blazor маршрутизатор становится интерактивным после статического SSR со статической маршрутизацией на сервере. Этот тип маршрутизации называется интерактивной маршрутизацией.

Статические маршрутизаторы используют маршрутизацию конечных точек и путь HTTP-запроса для определения компонента для отрисовки. Когда маршрутизатор становится интерактивным, он использует URL-адрес документа (URL-адрес в адресной строке браузера) для определения компонента для отрисовки. Это означает, что интерактивный маршрутизатор может динамически изменять, какой компонент отображается, если URL-адрес документа динамически изменяется на другой допустимый внутренний URL-адрес, и он может сделать это без выполнения HTTP-запроса для получения нового содержимого страницы.

Интерактивная маршрутизация также предотвращает предварительное отображение, так как новое содержимое страницы не запрашивается с сервера с обычным запросом страницы. Дополнительные сведения см. в разделе "Предварительная ASP.NET Основные Razor компоненты".

Компонент Router обеспечивает маршрутизацию к Razor компонентам и находится в компоненте приложения Routes (Components/Routes.razor).

Компонент Router обеспечивает маршрутизацию к Razor компонентам. Компонент Router используется в компоненте App (App.razor).

@page "/blazor-route"
@page "/different-blazor-route"

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

@page "/blazor-route"
@page "/different-blazor-route"

<PageTitle>Routing</PageTitle>

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Blazor routing</h1>

Router не взаимодействует со строковыми значениями запроса. Сведения о работе со строками запроса см. в разделе "Строки запроса".

Фокусировка элемента на навигации

Компонент FocusOnNavigate задает фокус пользовательского интерфейса элементу на основе селектора CSS после перехода с одной страницы на другую.

<FocusOnNavigate RouteData="routeData" Selector="h1" />

Когда компонент Router переходит на новую страницу, компонент FocusOnNavigate устанавливает фокус на заголовок верхнего уровня страницы (<h1>). Это общая стратегия обеспечения того, чтобы навигация по страницам была объявлена при использовании средства чтения с экрана.

Этот раздел относится к Blazor Web Apps.

Router Используйте параметр компонента AdditionalAssemblies и построитель AddAdditionalAssemblies соглашений о конечной точке для обнаружения routable компонентов в дополнительных сборках. В следующих подразделах объясняется, когда и как использовать каждый API.

Статическая маршрутизация

Чтобы обнаружить маршрутизируемые компоненты из дополнительных сборок для отрисовки на стороне статического сервера (статический SSR), даже если маршрутизатор позже становится интерактивным для интерактивной отрисовки, сборки должны быть раскрыты на Blazor платформе. AddAdditionalAssemblies Вызовите метод с дополнительными сборками, привязанными к MapRazorComponents файлу проекта Program сервера.

В следующем примере перечислены компоненты, которые можно перенаследовать в сборке BlazorSample.Client проекта с помощью файла проекта _Imports.razor :

app.MapRazorComponents<App>()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

Интерактивная маршрутизация

Интерактивный режим отрисовки можно назначить Routes компоненту (Routes.razor), который делает Blazor маршрутизатор интерактивным после статического SSR и статической маршрутизации на сервере. Например, <Routes @rendermode="InteractiveServer" /> компоненту назначается интерактивная отрисовка на стороне Routes сервера (интерактивная служба SSR). Компонент Router наследует интерактивную отрисовку на стороне Routes сервера (интерактивная служба SSR) от компонента. Маршрутизатор становится интерактивным после статической маршрутизации на сервере.

Внутренняя навигация для интерактивной маршрутизации не включает запрос нового содержимого страницы с сервера. Поэтому предварительное отображение не выполняется для внутренних запросов страниц. Дополнительные сведения см. в разделе "Предварительная ASP.NET Основные Razor компоненты".

Routes Если компонент определен в серверном проекте, AdditionalAssemblies параметр Router компонента должен включать .Client сборку проекта. Это позволяет маршрутизатору работать правильно при интерактивном отображении.

В следующем примере Routes компонент находится в серверном проекте, а _Imports.razor файл BlazorSample.Client проекта указывает сборку для поиска routable компонентов:

<Router
    AppAssembly="..."
    AdditionalAssemblies="new[] { typeof(BlazorSample.Client._Imports).Assembly }">
    ...
</Router>

В дополнение к сборке, указанной в AppAssembly, проверяются дополнительные сборки.

Кроме того, в проекте существуют .Client только routable components with global Interactive WebAssembly или Auto rendering, а Routes компонент определен в .Client проекте, а не серверный проект. В этом случае нет внешних сборок с маршрутизируемыми компонентами, поэтому не нужно указывать значение для AdditionalAssemblies.

Этот раздел относится к приложениям Blazor Server.

Router Используйте параметр компонента AdditionalAssemblies и построитель AddAdditionalAssemblies соглашений о конечной точке для обнаружения routable компонентов в дополнительных сборках.

В следующем примере — это routable компонент, Component1 определенный в указанной библиотеке классов компонентов с именем ComponentLibrary:

<Router
    AppAssembly="..."
    AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }">
    ...
</Router>

В дополнение к сборке, указанной в AppAssembly, проверяются дополнительные сборки.

@page "/route-parameter-1/{text}"

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

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

@page "/route-parameter-1/{text}"

<PageTitle>Route Parameter 1</PageTitle>

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

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

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

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

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

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

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }
}

@page "/route-parameter-1/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }
}

Поддерживаются необязательные параметры. В следующем примере необязательный параметр text назначает значение сегмента маршрута свойству Text компонента. Если сегмента нет, для Text устанавливается значение fantastic.

Необязательные параметры не поддерживаются. В приведенном ниже примере применяются две директивы @page. Первая позволяет переходить к компоненту без параметра. Вторая директива присваивает значение параметра маршрута {text} свойству Text компонента.

@page "/route-parameter-2/{text?}"

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

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

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

@page "/route-parameter-2/{text?}"

<PageTitle>Route Parameter 2</PageTitle>

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

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

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

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

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

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

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2/{text?}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

@page "/route-parameter-2"
@page "/route-parameter-2/{text}"

<h1>Blazor is @Text!</h1>

@code {
    [Parameter]
    public string Text { get; set; }

    protected override void OnParametersSet()
    {
        Text = Text ?? "fantastic";
    }
}

Ограничения маршрута также работают с необязательными параметрами. В следующем примере Id является обязательным параметром, а Option — необязательным логическим параметром маршрута.

User.razor:

@page "/user/{id:int}/{option:bool?}"

<p>
    Id: @Id
</p>

<p>
    Option: @Option
</p>

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

    [Parameter]
    public bool Option { get; set; }
}

Маршрутизация URL-адресов, содержащих точки

Шаблон маршрута на стороне сервера предполагает, что если последний сегмент URL-адреса запроса содержит точку (.), которую запрашивает файл. Например, относительный URL-адрес /example/some.thing интерпретируется маршрутизатором как запрос файла с именем some.thing. Без дополнительной настройки приложение возвращает ответ 404 — не найден ответ, если some.thing он предназначен для маршрутизации в компонент с @page директивой и some.thing является значением параметра маршрута. Чтобы использовать маршрут с одним параметром или несколькими, содержащими точку, в приложении необходимо настроить маршрут с помощью пользовательского шаблона.

Рассмотрим приведенный ниже компонент Example, который может получать параметр маршрута из последнего сегмента URL-адреса.

Example.razor:

@page "/example/{param?}"

<p>
    Param: @Param
</p>

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

@page "/example/{param?}"

<p>
    Param: @Param
</p>

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

@page "/example/{param?}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string Param { get; set; }
}

@page "/example"
@page "/example/{param}"

<p>
    Param: @Param
</p>

@code {
    [Parameter]
    public string Param { get; set; }
}

Чтобы разрешить Server приложению размещенного Blazor WebAssemblyрешения маршрутизировать запрос с точкой в param параметре маршрута, добавьте резервный шаблон маршрута файла с необязательным параметром в Program файле:

app.MapFallbackToFile("/example/{param?}", "index.html");

Чтобы настроить Blazor Server приложение для маршрутизации запроса с точкой в param параметре маршрута, добавьте резервный шаблон маршрута страницы с необязательным параметром Program в файле:

app.MapFallbackToPage("/example/{param?}", "/_Host");

Подробные сведения см. в статье Маршрутизация в ASP.NET Core.

Чтобы позволить приложению Server размещенного решения Blazor WebAssembly маршрутизировать запрос с точкой в параметре маршрута param, добавьте шаблон резервного маршрута к файлу с дополнительным параметром в Startup.Configure.

Startup.cs:

endpoints.MapFallbackToFile("/example/{param?}", "index.html");

Чтобы позволить приложению Blazor Server маршрутизировать запрос с точкой в параметре маршрута param, добавьте шаблон резервного маршрута к странице с дополнительным параметром в Startup.Configure.

Startup.cs:

endpoints.MapFallbackToPage("/example/{param?}", "/_Host");

Подробные сведения см. в статье Маршрутизация в ASP.NET Core.

Параметры маршрута catch-all

В компонентах поддерживаются параметры маршрута catch-all, которые захватывают пути в нескольких папках.

Параметры маршрута catch-all

• Его имя должно соответствовать имени сегмента маршрута. Именование не учитывает регистр.
• Тип string. Платформа не обеспечивает автоматическое приведение.
• В конце URL-адреса.

CatchAll.razor:

@page "/catch-all/{*pageRoute}"

<PageTitle>Catch All</PageTitle>

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

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

@page "/catch-all/{*pageRoute}"

<PageTitle>Catch All</PageTitle>

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

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

@page "/catch-all/{*pageRoute}"

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

@page "/catch-all/{*pageRoute}"

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

@page "/catch-all/{*pageRoute}"

@code {
    [Parameter]
    public string PageRoute { get; set; }
}

Для URL-адреса /catch-all/this/is/a/test с шаблоном маршрута /catch-all/{*pageRoute} значение PageRoute равно this/is/a/test.

Косые черты и сегменты захваченного пути декодированы. Для шаблона маршрута /catch-all/{*pageRoute} URL-адрес /catch-all/this/is/a%2Ftest%2A возвращает this/is/a/test*.

@page "/navigate"
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<PageTitle>Navigate</PageTitle>

<h1>Navigate Example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent() => Navigation.NavigateTo("counter");

    protected override void OnInitialized() => 
        Navigation.LocationChanged += HandleLocationChanged;

    private void HandleLocationChanged(object? sender, LocationChangedEventArgs e) => 
        Logger.LogInformation("URL of new location: {Location}", e.Location);

    public void Dispose() => Navigation.LocationChanged -= HandleLocationChanged;
}

@page "/navigate"
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<PageTitle>Navigate</PageTitle>

<h1>Navigate Example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent() => Navigation.NavigateTo("counter");

    protected override void OnInitialized() => 
        Navigation.LocationChanged += HandleLocationChanged;

    private void HandleLocationChanged(object? sender, LocationChangedEventArgs e) => 
        Logger.LogInformation("URL of new location: {Location}", e.Location);

    public void Dispose() => Navigation.LocationChanged -= HandleLocationChanged;
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent()
    {
        Navigation.NavigateTo("counter");
    }

    protected override void OnInitialized()
    {
        Navigation.LocationChanged += HandleLocationChanged;
    }

    private void HandleLocationChanged(object? sender, LocationChangedEventArgs e)
    {
        Logger.LogInformation("URL of new location: {Location}", e.Location);
    }

    public void Dispose()
    {
        Navigation.LocationChanged -= HandleLocationChanged;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent()
    {
        Navigation.NavigateTo("counter");
    }

    protected override void OnInitialized()
    {
        Navigation.LocationChanged += HandleLocationChanged;
    }

    private void HandleLocationChanged(object? sender, LocationChangedEventArgs e)
    {
        Logger.LogInformation("URL of new location: {Location}", e.Location);
    }

    public void Dispose()
    {
        Navigation.LocationChanged -= HandleLocationChanged;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent()
    {
        Navigation.NavigateTo("counter");
    }

    protected override void OnInitialized()
    {
        Navigation.LocationChanged += HandleLocationChanged;
    }

    private void HandleLocationChanged(object sender, LocationChangedEventArgs e)
    {
        Logger.LogInformation("URL of new location: {Location}", e.Location);
    }

    public void Dispose()
    {
        Navigation.LocationChanged -= HandleLocationChanged;
    }
}

@page "/navigate"
@using Microsoft.Extensions.Logging 
@implements IDisposable
@inject ILogger<Navigate> Logger
@inject NavigationManager Navigation

<h1>Navigate in component code example</h1>

<button class="btn btn-primary" @onclick="NavigateToCounterComponent">
    Navigate to the Counter component
</button>

@code {
    private void NavigateToCounterComponent()
    {
        Navigation.NavigateTo("counter");
    }

    protected override void OnInitialized()
    {
        Navigation.LocationChanged += HandleLocationChanged;
    }

    private void HandleLocationChanged(object sender, LocationChangedEventArgs e)
    {
        Logger.LogInformation("URL of new location: {Location}", e.Location);
    }

    public void Dispose()
    {
        Navigation.LocationChanged -= HandleLocationChanged;
    }
}

Улучшенная навигация и обработка форм

Этот раздел относится к Blazor Web Apps.

Blazor Web Apps поддерживает два типа маршрутизации для запросов навигации по страницам и обработки форм:

• Обычная навигация (перекрестная навигация по документу): для URL-адреса запроса активируется полная перезагрузка.
• Улучшенная навигация (навигация с тем же документом): Blazor перехватывает запрос и выполняет fetch запрос. Blazor затем исправляет содержимое ответа в DOM страницы. BlazorУлучшенная навигация и обработка форм избежать необходимости полностраничной перезагрузки и сохраняет больше состояния страницы, поэтому страницы загружаются быстрее, как правило, без потери позиции прокрутки пользователя на странице.

Улучшенная навигация доступна при следующих случаях:

• Скрипт Blazor Web App (blazor.web.js) используется, а не Blazor Server скрипт (blazor.server.js) или Blazor WebAssembly скрипт (blazor.webassembly.js).
• Эта функция не отключена явным образом.
• URL-адрес назначения находится в пределах внутреннего базового пространства URI (базовый путь приложения).

Если включена маршрутизация на стороне сервера и расширенная навигация, обработчики изменения расположения вызываются только для программной навигации, инициированной из интерактивной среды выполнения. В будущих выпусках дополнительные типы навигации, такие как ссылка, также могут вызывать обработчики изменения расположения.

Когда происходит расширенная навигация, обработчики событий, LocationChanged зарегистрированные в интерактивном сервере и среде выполнения WebAssembly, обычно вызываются. Существуют случаи, когда обработчики изменения расположения могут не перехватывать расширенную навигацию. Например, пользователь может переключиться на другую страницу перед тем, как интерактивная среда выполнения станет доступной. Поэтому важно, чтобы логика приложения не зависела от вызова обработчика изменения расположения, так как не гарантируется выполнение обработчика.

При вызове NavigateTo:

• falseЗначение forceLoad по умолчанию:
  • И расширенная навигация доступна по текущему 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 Запуск CoreBlazor.

Улучшенная навигация с помощью статической отрисовки на стороне сервера (статический SSR) требует особого внимания при загрузке JavaScript. Дополнительные сведения см. в разделе ASP.NET Core Blazor JavaScript со статическим отображением на стороне сервера (статический SSR).

Состояние журнала навигации

NavigationManager использует API журнала браузера, чтобы поддерживать состояние журнала навигации, куда заносятся изменения расположения, внесенные приложением. Состояние журнала особенно полезно в сценариях внешнего перенаправления, например при проверке подлинности пользователей с внешними identity поставщиками. Дополнительные сведения см. в разделе Параметры навигации.

Параметры навигации

Передайте NavigationOptions для NavigateTo для управления следующим поведением:

• ForceLoad: обход маршрутизации на стороне клиента и принудительная загрузка новой страницы с сервера, независимо от того, обрабатывается ли универсальный код ресурса клиентским маршрутизатором. Значение по умолчанию — false.
• ReplaceHistoryEntry: замена текущей записи в стеке журнала. Если false, добавьте новую запись в стек журнала. Значение по умолчанию — false.
• HistoryEntryState: возвращает или задает состояние для добавления к записи журнала.

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

Дополнительные сведения о получении состояния, связанного с записью в целевой журнал при обработке изменений расположения, см. в разделе Обработка и предотвращение изменений расположения.

[SupplyParameterFromQuery] Используйте атрибут, чтобы указать, что параметр компонента поступает из строки запроса.

Используйте атрибут с [Parameter] атрибутом, чтобы указать, что параметр компонента routable компонента поступает из строки запроса.[SupplyParameterFromQuery]

Параметры компонента, предоставляемые из строки запроса, поддерживают следующие типы:

• bool, DateTime, decimalintdoublestringfloatGuidlong.
• Варианты, допускающие значение NULL, для перечисленных выше типов.
• Массивы предыдущих типов, допускающие или не допускающие значение NULL.

Корректное форматирование для инвариантных языка и региональных параметров применяется для данного типа (CultureInfo.InvariantCulture).

Укажите свойство Name атрибута [SupplyParameterFromQuery], чтобы использовать имя параметра запроса, отличное от имени параметра компонента. В следующем примере в 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] свойства всегда public являются свойствами в .NET 6/7. В .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, а значение равно null.
• Корректное форматирование для инвариантных языка и региональных параметров применяется для данного типа (CultureInfo.InvariantCulture).
• Имя и значение параметра запроса кодируются в виде URL-адреса.
• Все значения с соответствующим именем параметра запроса заменяются при наличии нескольких экземпляров типа.

Вызовите GetUriWithQueryParameters для создания URI, созданного из Uri, с добавлением, обновлением или удалением нескольких параметров. Для каждого значения платформа использует value?.GetType() для определения типа среды выполнения каждого параметра запроса и выбирает правильное форматирование инвариантных языка и региональных параметров. Платформа выдает ошибку для неподдерживаемых типов.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

Заполнитель {PARAMETERS} является IReadOnlyDictionary<string, object>.

Передайте строку URI в GetUriWithQueryParameters, чтобы создать новый URI из предоставленного URI с несколькими добавленными, обновленными или удаленными параметрами. Для каждого значения платформа использует value?.GetType() для определения типа среды выполнения каждого параметра запроса и выбирает правильное форматирование инвариантных языка и региональных параметров. Платформа выдает ошибку для неподдерживаемых типов. Поддерживаемые типы перечислены далее в этом разделе.

@inject NavigationManager Navigation

...

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

• Заполнитель {URI} — это универсальный код ресурса (URI) со строкой запроса или без нее.
• Заполнитель {PARAMETERS} является IReadOnlyDictionary<string, object>.

Поддерживаемые типы идентичны поддерживаемым типам для ограничений маршрута:

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

К поддерживаемым типам относятся:

• Варианты, допускающие значение NULL, для перечисленных выше типов.
• Массивы предыдущих типов, допускающие или не допускающие значение NULL.

Замена значения параметра запроса, если параметр существует

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 см. в статье Вызов функций JavaScript из методов .NET в ASP.NET Core Blazor.

Хэшированная маршрутизация в именованные элементы

Перейдите к именованным элементу, используя следующие подходы с хэш-ссылкой на# элемент. Маршруты к элементам в компоненте и маршруты к элементам во внешних компонентах используют корневой относительный путь. Косая черта/ () является необязательной.

Примеры для каждого из следующих подходов демонстрируют навигацию к элементу с элементом с компонентом id targetElement Counter :

• Элемент Привязки (<a>) с элементом 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>

Добавьте следующий HashedRouting компонент в приложение.

HashedRouting.razor:

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

<PageTitle>Hashed routing</PageTitle>

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

<ul>
    <li>
        <a href="/hashed-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="/hashed-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");
    }
}

Взаимодействие пользователей с содержимым <Navigating>

Если во время навигации наблюдается значительная задержка, например при отложенной загрузке сборок в Blazor WebAssembly приложении или медленном сетевом подключении к Blazor серверу, компонент может указать пользователю, Router что переход страницы происходит.

В верхней части компонента, указывающего Router компонент, добавьте директиву @using для Microsoft.AspNetCore.Components.Routing пространства имен:

@using Microsoft.AspNetCore.Components.Routing

Предоставьте содержимое параметру Navigating для отображения во время событий перехода страницы.

Содержимое элемента<Router>...</Router> маршрутизатора:

<Navigating>
    <p>Loading the requested page&hellip;</p>
</Navigating>

Пример, в котором используется свойство Navigating, см. Сборки с отложенной загрузкой в ASP.NET Core Blazor WebAssembly.

Обработка события асинхронной навигации с помощью OnNavigateAsync

Компонент Router поддерживает функцию OnNavigateAsync. Обработчик OnNavigateAsync вызывается, когда пользователь выполняет следующие действия:

• попадает на маршрут в первый раз, перейдя к нему непосредственно в браузере;
• переходит на новый маршрут с помощью ссылки или вызова NavigationManager.NavigateTo.

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

<Router AppAssembly="typeof(Program).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

Пример, в котором используется OnNavigateAsync, см. Сборки с отложенной загрузкой в ASP.NET Core Blazor WebAssembly.

При предварительной подготовке на сервере OnNavigateAsync выполняется дважды:

• Один раз, когда запрошенный компонент конечной точки изначально отрисовывается статически.
• И второй раз, когда браузер отрисовывает компонент конечной точки.

Чтобы предотвратить выполнение кода разработчика дважды, Routes компонент может хранить NavigationContext для использования в OnNavigateAsync методеOnAfterRender{Async} жизненного цикла, где firstRender можно проверить. Дополнительные сведения см. в разделе "Предварительная отрисовка с помощью взаимодействия JavaScript".

Чтобы код разработчика в OnNavigateAsync не выполнялся дважды, компонент App может хранить NavigationContext для использования в OnAfterRender{Async}, где можно проверить firstRender. Дополнительные сведения см. в разделе "Предварительная отрисовка с помощью взаимодействия JavaScript".

Обработка отмены в OnNavigateAsync

Объект NavigationContext, переданный в обратный вызов OnNavigateAsync, содержит CancellationToken, который задается при возникновении нового события навигации. Обратный вызов OnNavigateAsync должен вызываться, если этот токен отмены установлен так, чтобы не выполнять обратный вызов OnNavigateAsync для устаревшей навигации.

Если пользователь переходит на конечную точку, а затем сразу переходит к новой конечной точке, приложение не должно продолжать выполнение обратного вызова OnNavigateAsync к первой конечной точке.

В следующем примере :

• Токен отмены передается в вызов PostAsJsonAsync, который может отменить запрос POST, если пользователь переходит от конечной точки /about.
• Токен отмены задается во время операции предварительной выборки продукта, если пользователь переходит от конечной точки /store.

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(Program).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

Обработка и предотвращение изменений расположения

RegisterLocationChangingHandler: регистрирует обработчик для обработки входящих событий навигации. Контекст обработчика, предоставляемый LocationChangingContext, включает следующие свойства:

• TargetLocation: возвращает конечное расположение.
• HistoryEntryState: возвращает состояние, связанное с записью в целевой журнал.
• IsNavigationIntercepted: возвращает значение, указывающее, была ли перехвачена навигация из ссылки.
• CancellationToken: возвращает значение CancellationToken, определяющее, была ли отменена навигация, например, чтобы определить, активировал ли пользователь другую навигацию.
• PreventNavigation: вызывается, чтобы предотвратить продолжение навигации.

Компонент может зарегистрировать несколько обработчиков изменения расположения в методе жизненного OnAfterRender{Async} цикла. Навигация вызывает все обработчики изменения расположения, зарегистрированные во всем приложении (между несколькими компонентами), и любая внутренняя навигация выполняет их одновременно. В дополнение к NavigateTo обработчики вызываются в следующих случаях:

• При нажатии на внутренние ссылки, которые указывают на URL-адреса в базовом пути приложения.
• При навигации с помощью кнопок "Вперед" и "Назад" в браузере.

Обработчики выполняются только для внутренней навигации в приложении. Если пользователь нажимает на ссылку, которая ведет на другой сайт, или вручную вводит в адресную строку адрес другого сайта, обработчики изменения расположения не выполняются.

Реализуйте IDisposable и удалите зарегистрированные обработчики для отмены регистрации. Дополнительные сведения см. в статье Жизненный цикл компонентов Razor ASP.NET Core.

В следующем примере обработчик изменения расположения регистрируется для событий навигации.

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-адресу в адресной строке браузера. Дополнительные сведения о требованиях взаимодействия см. в разделе Окно: событие beforeunload (документация по MDN).
• OnBeforeInternalNavigation задает обратный вызов для внутренних событий навигации.

Следующий компонент NavLock:

• Пользователь должен подтвердить попытку перейти по ссылке на веб-сайт Майкрософт перед успешной навигацией https://www.microsoft.com.
• PreventNavigation вызывается, чтобы предотвратить переход, если пользователь отказывается подтвердить навигацию с помощью вызова взаимодействия JavaScript (JS), который создает диалоговое окно JSconfirm.

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 пример приложения.

Этот раздел относится к Blazor Web Appоперационным системам по каналу.

Этот раздел относится к приложениям Blazor Server.

A Blazor Web App интегрирована в ASP.NET маршрутизации основных конечных точек. Приложение ASP.NET Core настроено на прием входящих подключений для интерактивных компонентов в MapRazorComponents Program файле. Корневой компонент по умолчанию (первый загруженный компонент) — это App компонент (App.razor):

app.MapRazorComponents<App>();

Blazor Server интегрирован с функцией маршрутизации конечных точек ASP.NET Core. Приложение ASP.NET Core настроено для приема входящих подключений для интерактивных компонентов в MapBlazorHub Program файле:

app.UseRouting();

app.MapBlazorHub();
app.MapFallbackToPage("/_Host");

Blazor Server интегрирован с функцией маршрутизации конечных точек ASP.NET Core. Приложение ASP.NET Core настроено для приема входящих подключений для интерактивных компонентов с помощью MapBlazorHub в Startup.Configure.

Типичная конфигурация — маршрутизация всех запросов на страницу Razor, которая выступает в качестве узла для серверной части приложения Blazor Server. По соглашению страница узла обычно называется _Host.cshtml и находится в папке Pages приложения.

Маршрут, указанный в файле узла, называется резервным маршрутом, так как он работает с низким приоритетом в соответствии с правилами маршрутизации. Резервный маршрут используется, если другие маршруты не сопоставляются. Это позволяет приложению использовать другие контроллеры и страницы, не мешая маршрутизации компонента в приложении Blazor Server.

Сведения о настройке MapFallbackToPage размещения сервера, отличного от корневого URL-адреса, см. в разделе "Узел" и развертывание ASP.NET Core Blazor.