Controlar o conteúdo <head> em aplicativos Blazor do ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Os componentes Razor podem modificar o conteúdo do elemento HTML <head> de uma página, incluindo a definição do título da página (elemento <title>) e a modificação de metadados (elementos <meta>).

Controlar o conteúdo <head> em um componente Razor

Especifique o título da página com o componente PageTitle, que permite renderizar um elemento HTML <title> em um HeadOutlet componente.

Especifique o conteúdo do elemento <head> com o componente HeadContent, que fornece conteúdo a um HeadOutlet componente.

O exemplo a seguir define o título e a descrição da página usando o Razor.

ControlHeadContent.razor:

@page "/control-head-content"

<PageTitle>@title</PageTitle>

<h1>Control <head> Content Example</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "This description is set by the component.";
    private string title = "Control <head> Content";
}

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

@page "/control-head-content"

<h1>Control <head> content</h1>

<p>
    Title: @title
</p>

<p>
    Description: @description
</p>

<PageTitle>@title</PageTitle>

<HeadContent>
    <meta name="description" content="@description">
</HeadContent>

@code {
    private string description = "Description set by component";
    private string title = "Title set by component";
}

Controlar o conteúdo <head> durante a pré-geração

Esta seção se aplica a aplicativos pré-gerados Blazor WebAssembly e aplicativos Blazor Server.

Quando os componentes Razor são pré-renderizados, o uso de uma página de layout (_Layout.cshtml) é necessário para controlar o conteúdo <head> com os componentes PageTitle e HeadContent. O motivo para esse requisito é que os componentes que controlam o conteúdo <head> devem ser renderizados antes do layout com o componente HeadOutlet. Essa ordem de renderização é necessária para controlar o conteúdo principal.

Se o arquivo compartilhado _Layout.cshtml não tiver um Auxiliar de Marca de Componente para um componente HeadOutlet, adicione-o aos elementos <head>.

Em um arquivo obrigatório, compartilhado _Layout.cshtml de um aplicativo Blazor Server ou aplicativo Razor Pages/MVC que insira componentes em páginas ou exibições:

<component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />

Em um arquivo obrigatório, compartilhado _Layout.cshtml de um aplicativo Blazor WebAssembly hospedado pré-gerado:

<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

Definir um título de página para componentes por meio de um layout

Defina o título da página em um componente de layout:

@inherits LayoutComponentBase

<PageTitle>Page Title</PageTitle>

<div class="page">
    ...  
</div>

componente HeadOutlet

O componente HeadOutlet renderiza o conteúdo fornecido por componentes PageTitle e HeadContent.

Em um aplicativo Web Blazor criado a partir do modelo de projeto, o componente HeadOutlet em App.razor renderiza o conteúdo <head>:

<head>
    ...
    <HeadOutlet />
</head>

Em aplicativos Blazor Server criados a partir do modelo de projeto Blazor Server, um Auxiliar de Marca de Componente renderiza o conteúdo <head> do componente HeadOutlet em Pages/_Host.cshtml:

<head>
    ...
    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
</head>

Em aplicativos Blazor Server criados a partir do modelo de projeto Blazor Server, um Auxiliar de Marca de Componente renderiza o conteúdo <head> do componente HeadOutlet em Pages/_Layout.cshtml:

<head>
    ...
    <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
</head>

Em um aplicativo criado a partir do modelo de projeto Blazor WebAssembly, o componente HeadOutlet é adicionado à coleção RootComponents do WebAssemblyHostBuilder no arquivo Program do lado do cliente:

builder.RootComponents.Add<HeadOutlet>("head::after");

Quando o ::after pseudo-seletor é especificado, o conteúdo do componente raiz é acrescentado ao conteúdo principal existente em vez de substituir o conteúdo. Isso permite que o aplicativo mantenha o conteúdo principal estático no wwwroot/index.html sem precisar repetir o conteúdo nos componentes Razor do aplicativo.

Definir um título de página padrão em um aplicativo Web Blazor

Definir o título da página no componente App (App.razor):

<head>
    ...
    <HeadOutlet />
    <PageTitle>Page Title</PageTitle>
</head>

Título de página não encontrado em um aplicativo Blazor WebAssembly

Nos aplicativos Blazor criados a partir do modelo de projeto de Aplicativo Autônomo Blazor WebAssembly, o modelo de componente NotFound no componente App (App.razor) define o título da página para Not found.

Em aplicativos Blazor criados a partir de um modelo de projeto Blazor, o modelo de componente NotFound no componente App (App.razor) define o título da página como Not found.

App.razor:

<NotFound>
    <PageTitle>Not found</PageTitle>
    ...
</NotFound>

Recursos adicionais

Documentação do Mozilla MDN Web Docs: