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

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

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

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

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

Интерактивная маршрутизация также предотвращает предварительное отображение, так как новое содержимое страницы не запрашивается с сервера с обычным запросом страницы. Дополнительные сведения см. в разделе Компоненты ASP.NET Core с предварительной отрисовкой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 для обнаружения маршрутизируемых компонентов в дополнительных сборках. В следующих подразделах объясняется, когда и как использовать каждый 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" /> назначает интерактивную отрисовку на стороне сервера (Interactive SSR) для компонента Routes. Компонент Router наследует интерактивную серверную отрисовку (интерактивное SSR) от компонента Routes. Маршрутизатор становится интерактивным после статической маршрутизации на сервере.

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

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

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

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

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

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

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

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

В следующем примере 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-адрес /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 параметры маршрутов, которые захватывают пути, проходящие через несколько границ папок.

Параметры маршрутов общего типа:

• Его имя должно соответствовать имени сегмента маршрута. Именование не чувствительно к регистру.
• Тип 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;
    }
}

В ASP.NET Core 10.0 (предварительная версия 4) ответы «Not Found» доступны только для статического SSR и глобальной интерактивной визуализации. Поддержка рендеринга на уровне страницы или компонента запланирована на релиз Preview 5 в июне 2025 года.

NavigationManager NotFound предоставляет метод для обработки сценариев, когда запрошенный ресурс не найден во время статического рендеринга на стороне сервера (SSR) или глобального интерактивного рендеринга:

• Статический SSR: вызов NotFound устанавливает код состояния HTTP на 404.
• Потоковая отрисовка: выбрасывает исключение, если запуск ответа уже начался.
• Интерактивная отрисовка: сигнализирует Blazor маршрутизатору (Router компоненту) для отрисовки не найденного содержимого.

Когда компонент отображается статически (статический SSR) и NavigationManager.NotFound вызывается, код состояния 404 устанавливается в ответе:

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

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

Два подхода к предоставлению содержимого "не найдено" для глобального интерактивного рендеринга:

• Используйте страницу "Не найдено" (компонент Razor).
• Укажите содержимое "не найдено" в свойстве компонента RouterNotFound (<NotFound>...</NotFound> разметка или путем задания параметра NotFound в качестве фрагмента отрисовки в коде C#).

В следующем примере используется страница "Не найдено" (NotFoundPage компонент) для отображения содержимого "Не найдено".

NotFoundPage.razor:

<h1>Not Found</h1>

<p>Sorry! Nothing to show.</p>

Укажите компонент NotFoundPage для компонента Router в Routes.razor. Возможно, потребуется указать пространство имен компонента с директивой @using в верхней части Routes.razor файла или в _Imports.razor файле.

<Router ...>
    <Found ...>
        ...
    </Found>
    <NotFound>
        <NotFoundPage />
    </NotFound>
</Router>

Когда компонент отрисовывается с помощью глобального интерактивного режима отрисовки, вызов NotFound подаёт сигнал маршрутизатору Blazor для отрисовки содержимого "Не найдено" — компонента NotFoundPage.

@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 можно использовать для уведомлений при вызове NotFound. Событие запускается только когда вызывается NotFound, а не для любого ответа с кодом 404. Например, установка HttpContextAccessor.HttpContext.Response.StatusCode в 404 не вызывает NotFound/OnNotFound.

В следующем примере для компонентов, которые используют интерактивную серверную отрисовку (Interactive SSR), настраиваемое содержимое отображается в зависимости от того, где вызывается OnNotFound. Если событие активируется следующим Movie компонентом, если фильм не найден при инициализации компонента, настраиваемое сообщение указывает, что запрошенный фильм не найден. Если событие активируется User компонентом, то другое сообщение указывает, что пользователь не найден.

Следующая NotFoundContext служба управляет контекстом и сообщением, если содержимое не найдено компонентами.

NotFoundContext.cs:

public class NotFoundContext
{
    public string Heading { get; private set; } = "Not Found";
    public string Message { get; private set; } = 
        "Sorry, the page that you requested couldn't be found.";

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

Служба регистрируется в серверном Program файле:

builder.Services.AddScoped<NotFoundContext>();

Компонент Routes (Routes.razor):

• Внедряет NotFoundContext службу.
• Отображает заголовок (Heading) и сообщение (Message), когда OnNotFound вызывается вызовом NotFound.

@inject NotFoundContext NotFoundContext

<Router AppAssembly="typeof(Program).Assembly">
    <Found Context="routeData">
        <RouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)" />
        <FocusOnNavigate RouteData="routeData" Selector="h1" />
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(Layout.MainLayout)">
            <h1>@NotFoundContext.Heading</h1> 
            <div>
                <p>@NotFoundContext.Message</p>
            </div>
        </LayoutView>
    </NotFound>
</Router>

В следующем примере показаны компоненты:

• Служба NotFoundContext внедряется вместе с NavigationManager.
• В OnInitializedAsync, HandleNotFound является обработчиком, назначенным для события OnNotFound. HandleNotFound вызывает NotFoundContext.UpdateContext для задания заголовка и сообщения для содержимого "Not Found", которое отображается компонентом Router в компоненте Routes (Routes.razor).
• Компоненты обычно используют идентификатор из параметра маршрута для получения фильма или пользователя из хранилища данных, например базы данных. В следующих примерах объект не возвращается (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. Идентификаторы сущностей, передаваемые в качестве параметров маршрута, в следующем примере являются фиктивными значениями, которые не оказывают эффекта, так как они фактически не используются компонентами, имитирующими отсутствие фильма или пользователя.

В 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 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:

• Если 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).
• Для 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 startup.

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

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

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

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

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

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

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

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

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

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

Корректное инвариантное форматирование относительно культуры применяется для данного типа (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-адресе.
  • Удаляется, если тип предоставленного значения является нулевой, а значение равно c0.
• Корректное инвариантное форматирование относительно культуры применяется для данного типа (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
• DateOnly
• DateTime
• decimal
• double
• float
• Guid
• int
• long
• string
• TimeOnly

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

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

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

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

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");
    }
}

Если во время навигации наблюдается значительная задержка, например при отложенной загрузке сборок в 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.

Компонент 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 выполняется дважды:

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

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

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

Объект 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: вызывается, чтобы предотвратить продолжение навигации.

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

В следующем компоненте NavLock:

• Прежде чем переход по ссылке на сайт Microsoft будет успешным, пользователь должен его подтвердить. 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).

Существует два параметра NavLinkMatch, которые можно назначить атрибуту Match элемента <NavLink>:

• NavLinkMatch.All: NavLink активна при совпадении с текущим URL-адресом, игнорируя строку запроса и фрагмент. Чтобы включить сопоставление по строке запроса/фрагменту, используйте переключатель Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragmentAppContext, установленный на true.
• NavLinkMatch.Prefix (по умолчанию) NavLink активен, если он соответствует любому префиксу текущего URL-адреса.

Существует два параметра NavLinkMatch, которые можно назначить атрибуту Match элемента <NavLink>:

• NavLinkMatch.All: NavLink активна при совпадении всего текущего URL-адреса, включая строку запроса и фрагмент.
• NavLinkMatch.Prefix (по умолчанию) NavLink активен, если он соответствует любому префиксу текущего URL-адреса.

Для применения пользовательской логики сопоставления создайте подкласс NavLink и переопределите его метод ShouldMatch. Верните true из метода, если вы хотите применить класс CSS active:

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

Для примера приведенного выше кода в приложении, которое можно запустить локально, получите Blazor Web App или Blazor WebAssembly образец приложения.

Этот раздел относится к Blazor Web Appсистемам, работающим через цепь.

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

A Blazor Web App интегрируется в маршрутизацию конечных точек ASP.NET Core. Приложение 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.