Roteamento e navegação do Blazor do ASP.NET Core

Roteamento estático versus interativo

Esta seção aplica-se a Blazor Web App.

Se a pré-renderização estiver habilitada, o roteador Blazor (componente Router, <Router> em Routes.razor) executará o roteamento estático para os componentes durante a renderização estática do lado do servidor (SSR estática). Esse tipo de roteamento é chamado de roteamento estático.

Quando um modo de renderização interativa é atribuído ao componente Routes, o roteador Blazor se torna interativo após a SSR estática com o roteamento estático no servidor. Esse tipo de roteamento é chamado de roteamento interativo.

Os roteadores estáticos usam o roteamento de ponto de extremidade e o caminho da solicitação HTTP para determinar qual componente será renderizado. Quando o roteador se torna interativo, ele usa a URL do documento (a URL na barra de endereços do navegador) para determinar qual componente será renderizado. Isso significa que o roteador interativo pode alterar dinamicamente qual componente é renderizado se a URL do documento for alterada dinamicamente para outra URL interna válida e poderá fazê-lo sem executar uma solicitação HTTP para buscar o novo conteúdo da página.

O roteamento interativo também impede a pré-renderização porque o novo conteúdo da página não é solicitado do servidor com uma solicitação de página normal. Para mais informações, confira Pré-renderizar componentes Razor do ASP.NET Core.

O componente Router habilita o roteamento para componentes Razore está localizado no componente Routes do aplicativo (Components/Routes.razor).

O componente Router permite o roteamento para componentes Razor. O componente Router é usado no componente 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>

O Router não interage com valores de cadeia de caracteres de consulta. Para trabalhar com cadeias de caracteres de consulta, confira a seção Cadeias de caracteres de consulta.

Concentrar um elemento na navegação

O componente FocusOnNavigate define o foco da interface do usuário em um elemento com base em um seletor CSS depois de navegar de uma página para outra.

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

Quando o componente Router navega para uma nova página, o componente FocusOnNavigate define o foco no cabeçalho de nível superior da página (<h1>). Essa é uma estratégia comum para garantir que uma navegação de página será anunciada no uso de um leitor de tela.

Esta seção aplica-se a Blazor Web App.

Use o parâmetro Router do componente AdditionalAssemblies e o construtor de convenções de ponto de extremidade AddAdditionalAssemblies para descobrir componentes roteáveis em assemblies adicionais. As subseções a seguir explicam quando e como usar cada API.

Roteamento estático

Para descobrir componentes roteáveis de assemblies adicionais para SSR estática, mesmo que o roteador mais tarde se torne interativo para renderização interativa, os assemblies deverão ser divulgados para a estrutura Blazor. Chame o método AddAdditionalAssemblies com os assemblies adicionais encadeados ao MapRazorComponents no arquivo Program do projeto do servidor.

O exemplo a seguir inclui os componentes roteáveis no assembly do projeto BlazorSample.Client usando o arquivo do projeto _Imports.razor:

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

Roteamento interativo

Um modo de renderização interativo pode ser atribuído ao componente Routes (Routes.razor) que torna o roteador Blazor interativo após a SSR estática e o roteamento estático no servidor. Por exemplo, <Routes @rendermode="InteractiveServer" /> atribui a renderização interativa do lado do servidor (SSR interativa) ao componente Routes. O componente Router herda a renderização interativa do lado do servidor (SSR interativa) do componente Routes. O roteador torna-se interativo após o roteamento estático no servidor.

A navegação interna para roteamento interativo não envolve a solicitação de novo conteúdo de página do servidor. Portanto, a pré-renderização não ocorre para solicitações de páginas internas. Para mais informações, confira Pré-renderizar componentes Razor do ASP.NET Core.

Se o componente Routes for definido no projeto do servidor, o parâmetro AdditionalAssemblies do componente Router deverá incluir o assembly do projeto .Client. Isso permite que o roteador funcione corretamente quando renderizado interativamente.

No exemplo a seguir, o componente Routes está no projeto do servidor e o arquivo _Imports.razor do projeto BlazorSample.Client indica o assembly para pesquisar componentes roteáveis:

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

Assemblies adicionais são verificados além do assembly especificado para AppAssembly.

Como alternativa, os componentes roteáveis só existem no projeto .Client com WebAssembly interativo global ou renderização automática aplicada e o componente Routes é definido no projeto .Client, não no projeto do servidor. Nesse caso, não há assemblies externos com componentes roteáveis, portanto, não é necessário especificar um valor para AdditionalAssemblies.

Esta seção aplica-se a aplicativos Blazor Server.

Use o parâmetro Router do componente AdditionalAssemblies e o construtor de convenções de ponto de extremidade AddAdditionalAssemblies para descobrir componentes roteáveis em assemblies adicionais.

No exemplo a seguir, Component1 é um componente roteável definido em uma biblioteca de classes de componente chamada ComponentLibrary:

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

Assemblies adicionais são verificados além do assembly especificado para 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; }
}

Há suporte a parâmetros opcionais. No exemplo a seguir, o parâmetro opcional text atribui o valor do segmento de rota à propriedade do Text componente. Se o segmento não estiver presente, o valor de Text será definido como fantastic.

Não há suporte a parâmetros posicionais. No exemplo a seguir, duas @page diretivas são aplicadas. A primeira diretiva permite a navegação para o componente sem um parâmetro. A segunda diretiva atribui o valor do parâmetro de rota {text} à propriedade Text do componente.

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

As restrições de rota também funcionam com parâmetros opcionais. No exemplo a seguir, Id é obrigatório, mas Option é um parâmetro de rota booliano opcional.

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

Roteamento com URLs que contêm pontos

Um modelo de rota padrão do lado do servidor pressupõe que, se o último segmento de uma URL de solicitação contiver um ponto (.), um arquivo será solicitado. Por exemplo, a URL relativa /example/some.thing é interpretada pelo roteador como uma solicitação de um arquivo chamado some.thing. Sem configuração adicional, um aplicativo retornará uma resposta 404 – Não encontrado se some.thing devesse rotear para um componente com uma diretiva @page e some.thing é um valor de parâmetro de rota. Para usar uma rota com um ou mais parâmetros que contenham um ponto, o aplicativo precisará configurar a rota com um modelo personalizado.

Considere o componente Example a seguir que pode receber um parâmetro de rota do último segmento da 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; }
}

Para permitir que o aplicativo Server de uma solução Blazor WebAssembly hospedada encaminhe a solicitação com um ponto no parâmetro de rota param, adicione um modelo de rota de arquivo de fallback com o parâmetro opcional no arquivo Program:

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

Para configurar um aplicativo Blazor Server para rotear a solicitação com um ponto no parâmetro de rota param, adicione um modelo de rota de página de fallback com o parâmetro opcional no arquivo Program:

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

Saiba mais em Roteamento no ASP.NET Core.

Para permitir que o aplicativo Server de uma solução Blazor WebAssemblyhospedada encaminhe a solicitação com um ponto no parâmetro de rota param, adicione um modelo de rota de arquivo de fallback com o parâmetro opcional em Startup.Configure.

Startup.cs:

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

Para configurar um aplicativo Blazor Server para rotear a solicitação com um ponto no parâmetro de rota param, adicione um modelo de rota de página de fallback com o parâmetro opcional em Startup.Configure.

Startup.cs:

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

Saiba mais em Roteamento no ASP.NET Core.

Parâmetros de rota catch-all

Os parâmetros de rota catch-all, que capturam caminhos entre vários limites de pasta, têm suporte nos componentes.

Os parâmetros de rota catch-all são:

• Nomeados de forma a corresponder ao nome do segmento de rota. A nomenclatura não diferencia maiúsculas de minúsculas.
• Um tipo string. A estrutura não fornece conversão automática.
• No final da 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; }
}

Para o /catch-all/this/is/a/test de URL com um modelo de rota de /catch-all/{*pageRoute}, o valor de PageRoute é definido como this/is/a/test.

Barras e segmentos do caminho capturado são decodificados. Para um modelo de rota de /catch-all/{*pageRoute}, o /catch-all/this/is/a%2Ftest%2A da URL gera 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;
    }
}

Navegação e tratamento de formulários aprimorados

Esta seção aplica-se a Blazor Web App.

Blazor Web Apps são capazes de dois tipos de roteamento para solicitações de navegação de página e tratamento de formulários:

• Navegação normal (navegação entre documentos): um recarregamento de página inteira é disparado para a URL de solicitação.
• Navegação aprimorada (navegação no mesmo documento): Blazor intercepta a solicitação e, em vez disso, executa uma solicitação fetch. Em seguida, Blazor aplica o patch do conteúdo de resposta no DOM da página. A navegação aprimorada e o tratamento de formulários de Blazor evitam a necessidade de um recarregamento de página inteira e preservam mais do estado da página, de modo que as páginas são carregadas mais rapidamente, sem perder a posição de rolagem do usuário na página.

A navegação aprimorada está disponível quando:

• O script do Blazor Web App (blazor.web.js) é usado, não o script do Blazor Server (blazor.server.js) ou o script do Blazor WebAssembly (blazor.webassembly.js).
• O recurso não está desabilitado explicitamente.
• A URL de destino está dentro do espaço interno do URI de base (o caminho base do aplicativo).

Se o roteamento do lado do servidor e a navegação aprimorada estiverem habilitados, manipuladores de alteração de local serão invocados apenas para navegação programática iniciada a partir de um runtime interativo. Em versões futuras, tipos adicionais de navegação, como seguir um link, também poderão invocar manipuladores de alteração de localização.

Quando ocorre uma navegação aprimorada, os manipuladores de eventos LocationChanged registrados junto ao Servidor Interativo e os runtimes do WebAssembly costumam ser invocados. Existem casos em que os manipuladores de alteração de localização poderão não interceptar uma navegação aprimorada. Por exemplo, o usuário poderá alternar para outra página antes de um runtime interativo ficar disponível. Portanto, é importante que a lógica do aplicativo não dependa da invocação de um manipulador de alteração de localização, já que não há garantia de execução do manipulador.

Ao chamar NavigateTo:

• Se forceLoad for false, que é o padrão:
  • E a navegação aprimorada estiver disponível na URL atual, a navegação aprimorada de Blazor será ativada.
  • Caso contrário, Blazor executará um recarregamento de página inteira para a URL solicitada.
• Se forceLoad for true: Blazor executará um carregamento de página inteira para a URL solicitada, independentemente de a navegação aprimorada estar disponível ou não.

Você pode atualizar a página atual chamando NavigationManager.Refresh(bool forceLoad = false), que sempre executa uma navegação aprimorada, se disponível. Se a navegação aprimorada não estiver disponível, Blazor executará um recarregamento de página inteira.

Navigation.Refresh();

Passe true para o parâmetro forceLoad para garantir que um recarregamento de página inteira seja sempre executada, mesmo se a navegação aprimorada estiver disponível:

Navigation.Refresh(true);

A navegação aprimorada está habilitada por padrão, mas pode ser controlada hierarquicamente e por link utilizando o atributo HTML data-enhance-nav.

Os exemplos a seguir desabilitam a navegação aprimorada:

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

Se o destino for um ponto de extremidade diferente de Blazor, a navegação aprimorada não será aplicada e o JavaScript do lado do cliente se repetirá como um carregamento de toda a página. Isso garante que não haja nenhuma confusão na estrutura sobre páginas externas que não devem ser corrigidas em uma página existente.

Para habilitar o tratamento aprimorado de formulários, adicione o parâmetro Enhance aos formulários EditForm ou o atributo data-enhance aos formulários HTML (<form>):

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

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

O tratamento aprimorado de formulários não é hierárquico e não flui para os formulários secundários:

❌Não suportado: não é possível definir a navegação aprimorada em um elemento ancestral do formulário para habilitar a navegação aprimorada para o formulário.

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

As postagens do formulário aprimorado só funcionam com pontos de extremidade Blazor. A postagem de um formulário aprimorado em um ponto de extremidade diferente de Blazor resulta em um erro.

Para desabilitar a navegação aprimorada:

• Para um EditForm, remova o parâmetro Enhance do elemento do formulário (ou defina-o como false: Enhance="false").
• Para um HTML <form>, remova o atributo data-enhance do elemento do formulário (ou defina-o como false: data-enhance="false").

A navegação aprimorada e o manuseio de formulários da Blazor podem desfazer alterações dinâmicas no DOM se o conteúdo atualizado não fizer parte da renderização do servidor. Para preservar o conteúdo de um elemento, utilize o atributo data-permanent.

No exemplo a seguir, o conteúdo do elemento <div> é atualizado dinamicamente por um script quando a página é carregada:

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

Uma vez que Blazor tenha sido iniciado no cliente, você poderá utilizar o evento enhancedload para escutar as atualizações aprimoradas da página. Isso permite a reaplicação de alterações no DOM que podem ter sido desfeitas por uma atualização de página aprimorada.

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

Para desabilitar a navegação aprimorada e o tratamento de formulários globalmente, consulte ASP.NET Core Blazor inicialização.

A navegação aprimorada com renderização estática do lado do servidor (SSR estática) exige atenção especial ao carregar o JavaScript. Para obter mais informações, confira JavaScript do ASP.NET Core Blazor com renderização estática do lado do servidor (SSR estática).

Estado do histórico de navegação

O NavigationManager usa a API de Histórico do navegador para manter o estado do histórico de navegação associado a cada alteração de local feita pelo aplicativo. Manter o estado do histórico é particularmente útil em cenários de redirecionamento externo, por exemplo, ao autenticar usuários com provedores de identity externos. Para obter mais informações, confira a seção Opções de Navegação.

Opções de navegação

Transmita NavigationOptions a NavigateTo para controlar os seguintes comportamentos:

• ForceLoad: ignora o roteamento do lado do cliente e força o navegador a carregar a nova página do servidor, independentemente de o URI ser manipulado pelo roteador do lado do cliente. O valor padrão é false.
• ReplaceHistoryEntry: substitui a entrada atual na pilha de histórico. Se false, acrescente a nova entrada à pilha de histórico. O valor padrão é false.
• HistoryEntryState: obtém ou define o estado a ser acrescentado à entrada de histórico.

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

Para obter mais informações sobre como obter o estado associado à entrada de histórico de destino durante o tratamento de alterações de local, confira a seção Manipular/impedir alterações de local.

Use o atributo [SupplyParameterFromQuery] para especificar que um parâmetro de componente é proveniente da cadeia de caracteres de consulta.

Use o atributo [SupplyParameterFromQuery] com o atributo [Parameter] para especificar que um parâmetro de componente de um componente roteável pode vir da cadeia de caracteres de consulta.

Os parâmetros de componente fornecidos da cadeia de caracteres de consulta dão suporte aos seguintes tipos:

• bool, DateTime, decimal, double, float, Guid, int, long, string.
• Variantes anuláveis dos tipos anteriores.
• Matrizes dos tipos anteriores, sejam anuláveis, sejam não anuláveis.

A formatação sem variação de cultura correta é aplicada ao tipo determinado (CultureInfo.InvariantCulture).

Especifique a propriedade Name do atributo [SupplyParameterFromQuery] para usar um nome de parâmetro de consulta diferente do nome do parâmetro do componente. No exemplo a seguir, o nome C# do parâmetro de componente é {COMPONENT PARAMETER NAME}. Um nome de parâmetro de consulta diferente é especificado para o espaço reservado {QUERY PARAMETER NAME}:

Ao contrário das propriedades de parâmetro do componente ([Parameter]), as propriedades [SupplyParameterFromQuery] podem ser marcadas private além de public.

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

Assim como as propriedades do parâmetro do componente ([Parameter]), as propriedades [SupplyParameterFromQuery] são sempre propriedades public no .NET 6/7. No .NET 8 ou posteriores, as propriedades [SupplyParameterFromQuery] podem ser marcadas public ou private.

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

No exemplo a seguir, com uma URL de /search?filter=scifi%20stars&page=3&star=LeVar%20Burton&star=Gary%20Oldman:

• A propriedade Filter resolve scifi stars.
• A propriedade Page resolve 3.
• A matriz Stars é preenchida com base em parâmetros de consulta chamados star (Name = "star") e resolve para LeVar Burton e 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; }
}

Use GetUriWithQueryParameter para adicionar, alterar ou remover um ou mais parâmetros de consulta na URL atual:

@inject NavigationManager Navigation

...

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

No exemplo anterior:

• O espaço reservado {NAME} especifica o nome do parâmetro de consulta. O espaço reservado {VALUE} especifica o valor como um tipo com suporte. Os tipos com suporte são listados posteriormente nesta seção.
• Uma cadeia de caracteres é retornada igual à URL atual com um único parâmetro:
  • Adicionado se o nome do parâmetro de consulta não existir na URL atual.
  • Atualizado para o valor fornecido se o parâmetro de consulta existir na URL atual.
  • Removido se o tipo do valor fornecido for anulável e o valor for null.
• A formatação sem variação de cultura correta é aplicada ao tipo determinado (CultureInfo.InvariantCulture).
• O nome e o valor do parâmetro de consulta são codificados em URL.
• Todos os valores com o nome do parâmetro de consulta correspondente serão substituídos se houver várias instâncias do tipo.

Chame GetUriWithQueryParameters para criar um URI construído de Uri com vários parâmetros adicionados, atualizados ou removidos. Para cada valor, a estrutura usa value?.GetType() a fim de determinar o tipo de runtime para cada parâmetro de consulta e seleciona a formatação invariável da cultura correta. A estrutura lança um erro para tipos sem suporte.

@inject NavigationManager Navigation

...

Navigation.GetUriWithQueryParameters({PARAMETERS})

O espaço reservado {PARAMETERS} é um IReadOnlyDictionary<string, object>.

Transmita uma cadeia de caracteres de URI para GetUriWithQueryParameters a fim de gerar um novo URI de um URI fornecido com vários parâmetros adicionados, atualizados ou removidos. Para cada valor, a estrutura usa value?.GetType() a fim de determinar o tipo de runtime para cada parâmetro de consulta e seleciona a formatação invariável da cultura correta. A estrutura lança um erro para tipos sem suporte. Os tipos com suporte são listados posteriormente nesta seção.

@inject NavigationManager Navigation

...

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

• O espaço reservado {URI} é o URI com ou sem uma cadeia de caracteres de consulta.
• O espaço reservado {PARAMETERS} é um IReadOnlyDictionary<string, object>.

Os tipos com suporte são idênticos aos tipos com suporte em restrições de rota:

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

Os tipos compatíveis incluem:

• Variantes anuláveis dos tipos anteriores.
• Matrizes dos tipos anteriores, sejam anuláveis, sejam não anuláveis.

Substitui um valor de parâmetro de consulta quando o parâmetro existe

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

Acrescenta um parâmetro de consulta e um valor quando o parâmetro não existe

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

Remove um parâmetro de consulta quando o valor do parâmetro é null

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

Adiciona, atualiza e remove parâmetros de consulta

No exemplo a seguir:

• name é removido, se presente.
• age é adicionado com um valor de 25 (int), se não estiver presente. Se estiver presente, age será atualizado para um valor de 25.
• eye color é adicionado ou atualizado para um valor de green.

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

Suporte a valores enumeráveis

No exemplo a seguir:

• full name é adicionado ou atualizado para Morena Baccarin, um valor único.
• ping parâmetros são adicionados ou substituídos por 35, 16, 87 e 240.

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

Navegar com uma cadeia de caracteres de consulta adicionada ou modificada

Para navegar com uma cadeia de caracteres de consulta adicionada ou modificada, transmita uma URL gerada a NavigateTo.

O exemplo abaixo chama:

• GetUriWithQueryParameter para adicionar ou substituir o parâmetro de consulta name usando um valor de Morena Baccarin.
• Chama NavigateTo a fim de disparar a navegação para a nova URL.

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

A cadeia de caracteres de consulta de uma solicitação é obtida da propriedade NavigationManager.Uri:

@inject NavigationManager Navigation

...

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

Para analisar os parâmetros de uma cadeia de consulta, uma abordagem é usar URLSearchParams com interoperabilidade JavaScript (JS):

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

Para obter mais informações sobre o isolamento JavaScript com módulos JavaScript, confira Chamar funções JavaScript de métodos do .NET no ASP.NET Core Blazor.

Roteamento de hash para elementos nomeados

Navegue até um elemento nomeado usando as abordagens a seguir com uma referência de hash (#) ao elemento. As rotas para elementos dentro do componente e as rotas para elementos em componentes externos usam caminhos relativos à raiz. Uma barra à esquerda (/) é opcional.

Exemplos para cada uma das abordagens a seguir demonstram a navegação para um elemento com um id do targetElement no componente Counter:

• Elemento âncora (<a>) com um href:

  <a href="/counter#targetElement">
  

• Componente NavLink com um href:

  <NavLink href="/counter#targetElement">
  

• NavigationManager.NavigateTo passando a URL relativa:

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

O exemplo a seguir demonstra o roteamento hash para títulos H2 nomeados dentro de um componente e para componentes externos.

Nos componentes Home (Home.razor) e Counter (Counter.razor), coloque a marcação a seguir na parte inferior da marcação de componente existente para servir como destinos de navegação. O <div> cria um espaço vertical artificial para demonstrar o comportamento de rolagem do navegador:

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

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

Adicione o componente HashedRouting a seguir ao aplicativo.

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

Interação do usuário com conteúdo <Navigating>

Se houver um atraso significativo durante a navegação, como durante o carregamento lento de assemblies em um aplicativo Blazor WebAssembly ou para uma conexão de rede lenta com um aplicativo Blazor do lado do servidor, o componente Router poderá indicar ao usuário que uma transição de página está ocorrendo.

Na parte superior do componente que especifica o componente Router, adicione uma diretiva @using para o namespace Microsoft.AspNetCore.Components.Routing:

@using Microsoft.AspNetCore.Components.Routing

Forneça conteúdo ao parâmetro Navigating para exibição durante eventos de transição de página.

No conteúdo do elemento roteador (<Router>...</Router>):

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

Para obter um exemplo que usa a propriedade Navigating, confira Assemblies de carga lentos no ASP.NET Core Blazor WebAssembly.

Manipular eventos de navegação assíncrona com OnNavigateAsync

O componente Router dá suporte a um recurso de OnNavigateAsync. O manipulador OnNavigateAsync é invocado quando o usuário:

• Visita uma rota pela primeira vez navegando até ela diretamente no navegador.
• Navega até uma nova rota usando um link ou uma invocação 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)
    {
        ...
    }
}

Para obter um exemplo que usa a propriedade OnNavigateAsync, confira Assemblies de carga lentos no Blazor WebAssembly do ASP.NET Core.

Ao pré-renderizar no servidor, OnNavigateAsync é executado duas vezes:

• Uma vez, quando o componente de ponto de extremidade solicitado é inicialmente renderizado estaticamente.
• Uma segunda vez quando o navegador renderiza o componente do ponto de extremidade.

Para impedir que o código do desenvolvedor em OnNavigateAsync seja executado duas vezes, o componente Routes pode armazenar o NavigationContext para uso no método de ciclo de vida OnAfterRender{Async}, em que firstRender pode ser verificado. Para mais informações, confira Pré-renderização com interop do JavaScript.

Para impedir que o código do desenvolvedor em OnNavigateAsync seja executado duas vezes, o componente App pode armazenar o NavigationContext para uso em OnAfterRender{Async}, em que firstRender pode ser verificado. Para mais informações, confira Pré-renderização com interop do JavaScript.

Manipular cancelamentos em OnNavigateAsync

O objeto NavigationContext transmitido ao retorno de chamada OnNavigateAsync contém um CancellationToken definido quando ocorre um novo evento de navegação. O retorno de chamada OnNavigateAsync precisa lançar quando esse token de cancelamento é definido a fim de evitar continuar a executar o retorno de chamada OnNavigateAsync em uma navegação desatualizada.

Se um usuário navegar até um ponto de extremidade, mas depois navegar imediatamente até um novo ponto de extremidade, o aplicativo não deverá continuar executando o retorno de chamada OnNavigateAsync para o primeiro ponto de extremidade.

No exemplo a seguir:

• O token de cancelamento é transmitido na chamada a PostAsJsonAsync, o que pode cancelar o POST se o usuário navegar para longe do ponto de extremidade /about.
• O token de cancelamento é definido durante uma operação de pré-busca do produto se o usuário navegar para longe do ponto de extremidade /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);
            }
        }
    }
}

Manipular/impedir alterações de local

RegisterLocationChangingHandlerRegistra um manipulador para processar eventos de navegação recebidos. O contexto do manipulador fornecido pelo LocationChangingContext inclui as seguintes propriedades:

• TargetLocation: obtém o local de destino.
• HistoryEntryState: obtém o estado associado à entrada do histórico de destino.
• IsNavigationIntercepted: obtém se a navegação foi interceptada de um link ou não.
• CancellationToken: obtém um CancellationToken para determinar se a navegação foi cancelada, por exemplo, para determinar se o usuário disparou uma navegação diferente.
• PreventNavigation: chamado para impedir que a navegação continue.

Um componente pode registrar vários manipuladores de alteração de local no método de ciclo de vida OnAfterRender{Async}. A navegação invoca todos os manipuladores de alteração de local registrados em todo o aplicativo (em vários componentes) e toda as navegações internas executam todos eles em paralelo. Além de NavigateTo, os manipuladores são invocados:

• Ao selecionar links internos, que são links que apontam para URLs no caminho base do aplicativo.
• Ao navegar usando os botões para frente e para trás em um navegador.

Os manipuladores são executados apenas para navegação interna dentro do aplicativo. Se o usuário selecionar um link que navegue até um site diferente ou alterar a barra de endereços para um site diferente manualmente, os manipuladores de alteração de localização não serão executados.

Implemente IDisposable e descarte manipuladores registrados para cancelá-los. Para saber mais, consulte Ciclo de vida de renderização de Razor no ASP.NET Core.

No exemplo a seguir, um manipulador de alteração de local é registrado para eventos de navegação.

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

Como a navegação interna pode ser cancelada de forma assíncrona, podem ocorrer várias chamadas sobrepostas a manipuladores registrados. Por exemplo, várias chamadas de manipulador podem ocorrer quando o usuário seleciona rapidamente o botão Voltar em uma página ou seleciona vários links antes de uma navegação ser executada. Veja abaixo um resumo da lógica de navegação assíncrona:

• Se algum manipulador de alteração de local for registrado, toda a navegação será inicialmente revertida e reproduzida se a navegação não for cancelada.
• Se forem feitas solicitações de navegação sobrepostas, a solicitação mais recente sempre cancelará solicitações anteriores, o que significa o seguinte:
  • O aplicativo pode tratar várias seleções de botão Voltar e encaminhar como uma única seleção.
  • Se o usuário selecionar vários links antes da conclusão da navegação, o último link selecionado determinará a navegação.

Para obter mais informações sobre como transmitir NavigationOptions a NavigateTo para controlar as entradas e o estado da pilha de histórico de navegação, confira a seção Opções de navegação.

Para obter um código de exemplo adicional, confira o NavigationManagerComponent no BasicTestApp (fonte de referência dotnet/aspnetcore).

O NavigationLock componente intercepta eventos de navegação desde que seja renderizado, efetivamente "bloqueando" qualquer navegação determinada até que seja tomada uma decisão de prosseguir ou cancelar. Use NavigationLock quando o escopo da interceptação de navegação puder ser definido como o tempo de vida de um componente.

Parâmetros de NavigationLock:

• ConfirmExternalNavigation define um diálogo do navegador para solicitar que o usuário confirme ou cancele a navegação externa. O valor padrão é false. A exibição do diálogo de confirmação requer a interação inicial do usuário com a página antes de disparar a navegação externa com a URL na barra de endereços do navegador. Para obter mais informações sobre o requisito de interação, confira Evento Window: beforeunload (documentação do MDN).
• OnBeforeInternalNavigation define um retorno de chamada para eventos de navegação interna.

No seguinte componente NavLock:

• Uma tentativa de seguir o link para o site da Microsoft precisa ser confirmada pelo usuário antes que a navegação até https://www.microsoft.com seja bem-sucedida.
• PreventNavigation é chamado para impedir que a navegação ocorra se o usuário se recusar a confirmar a navegação por meio de uma chamada de interoperabilidade JavaScript (JS) que gera o JSconfirm diálogo.

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

Para obter um código de exemplo adicional, confira o componente ConfigurableNavigationLock no BasicTestApp (fonte de referência dotnet/aspnetcore).

Para ver um exemplo do código anterior em um aplicativo de exemplo que você pode executar localmente, obtenha o Blazor Web App ou o aplicativo de exemplo Blazor WebAssembly.

Essa seção se aplica aos Blazor Web Apps que operam em um circuito.

Esta seção aplica-se a aplicativos Blazor Server.

O Blazor Web App é integrado ao Roteamento de Ponto de Extremidade do ASP.NET. Core. Um aplicativo ASP.NET Core é configurado para aceitar conexões de entrada para componentes interativos com MapRazorComponents no arquivo Program. O componente raiz padrão (primeiro componente carregado) é o componente App (App.razor):

app.MapRazorComponents<App>();

O Blazor Server é integrado ao Roteamento de Ponto de Extremidade do ASP.NET. Core. Um aplicativo ASP.NET Core é configurado para aceitar conexões de entrada para componentes interativos com MapBlazorHub no arquivo Program:

app.UseRouting();

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

O Blazor Server é integrado ao Roteamento de Ponto de Extremidade do ASP.NET. Core. Um aplicativo ASP.NET Core é configurado para aceitar conexões de entrada para componentes interativos com MapBlazorHub no Startup.Configure.

A configuração típica é rotear todas as solicitações para uma Razor Page, que atua como o host do aplicativo Blazor Server do lado do servidor. Por convenção, a página host geralmente é nomeada _Host.cshtml na pasta Pages do aplicativo.

A rota especificada no arquivo de host é chamada de rota de fallback porque opera com baixa prioridade na correspondência de rotas. A rota de fallback é usada quando outras rotas não correspondem. Isso permite que o aplicativo use outros controladores e páginas sem interferir no roteamento de componentes no aplicativo Blazor Server.

Para obter informações sobre como configurar o MapFallbackToPage para hospedagem de servidor de URL não raiz, confira Hospedar e implantar o ASP.NET Core Blazor.