ASP.NET Core Blazor seções

Observação

Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão do .NET 10 deste artigo.

Este artigo explica como controlar o conteúdo em um componente Razor de um componente de filho Razor.

Seções Blazor

Para controlar o conteúdo em um Razor componente de um componente filho Razor, Blazor suporta seções usando os seguintes componentes integrados:

• SectionOutlet: Renderiza o conteúdo fornecido por SectionContent componentes com argumentos SectionName ou SectionId correspondentes. Dois ou mais componentes SectionOutlet não podem ter o mesmo SectionName ou SectionId.

• SectionContent: Fornece conteúdo como um RenderFragment para SectionOutlet componentes com um SectionName ou SectionId correspondente. Se vários componentes SectionContent tiverem o mesmo SectionName ou SectionId, o componente SectionOutlet correspondente renderizará o conteúdo do último renderizado SectionContent.

As seções podem ser usadas em layouts e em componentes pai-filho aninhados.

Embora o argumento passado para SectionName possa usar qualquer tipo de capitalização, a documentação adota a capitalização kebab (por exemplo, top-bar), que é uma escolha comum de capitalização para IDs de elemento HTML. SectionId recebe um campo object estático e sempre recomendamos maiúsculas e minúsculas Pascal para nomes de campo C# (por exemplo, TopbarSection).

No exemplo a seguir, o componente de layout principal do aplicativo implementa um botão de contador de incremento para o componente Counter do aplicativo.

Se o namespace das seções não estiver no arquivo _Imports.razor adicione-o:

@using Microsoft.AspNetCore.Components.Sections

No componente MainLayout (MainLayout.razor), coloque um componente SectionOutlet e passe uma string para o parâmetro SectionName para indicar o nome da seção. O exemplo a seguir usa o nome da seção top-bar:

<SectionOutlet SectionName="top-bar" />

No Counter componente (Counter.razor), crie um SectionContent componente e passe a cadeia de caracteres correspondente (top-bar) para seu SectionName parâmetro:

<SectionContent SectionName="top-bar">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</SectionContent>

Quando o componente Counter é acessado em /counter, o componente MainLayout renderiza o botão de contagem de incremento do componente Counter onde o componente SectionOutlet é colocado. Quando qualquer outro componente é acessado, o botão de contagem de incremento não é renderizado.

Em vez de usar uma seção nomeada, você pode passar um object estático com o parâmetro SectionId para identificar a seção. O exemplo a seguir também implementa um botão de contador de incremento para o componente Counter do aplicativo no layout principal do aplicativo.

Se você não quiser que outros componentes SectionContent coincidam acidentalmente com o nome de um SectionOutlet, passe um parâmetro de objeto SectionId para identificar a seção. Isso pode ser útil ao projetar uma Razor biblioteca de classes (RCL). Quando um SectionOutlet no RCL usa uma referência de objeto com SectionId e o consumidor coloca um componente SectionContent com um objeto SectionId correspondente, uma correspondência acidental por nome não é possível quando os consumidores do RCL implementam outros componentes SectionContent.

O exemplo a seguir também implementa um botão de contador de incremento para o componente Counter do aplicativo no layout principal do aplicativo, usando uma referência de objeto em vez de um nome de seção.

Adicione um TopbarSection static object ao MainLayout componente em um @code bloco:

@code {
    internal static object TopbarSection = new();
}

Na marcação do MainLayout componente Razor, coloque um SectionOutlet componente e passe TopbarSection para o parâmetro SectionId para indicar a seção:

<SectionOutlet SectionId="TopbarSection" />

Adicione um componente SectionContent ao componente Counter do aplicativo que renderiza um botão de contagem de incremento. Use a seção estática MainLayout do TopbarSection componente object como o SectionId (MainLayout.TopbarSection).

No Counter.razor:

<SectionContent SectionId="MainLayout.TopbarSection">
    <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
</SectionContent>

Quando o componente Counter é acessado, o componente MainLayout renderiza o botão de contagem de incrementos onde o componente SectionOutlet é colocado.

Observação

SectionOutlet e SectionContent os componentes só podem definir SectionId ou SectionName, não ambos.

RenderFragment Regras de cache e comportamento de renderização de seção

Quando o conteúdo de um SectionContent's RenderFragment é alterado, que é uma instância diferente do componente em que ele é renderizado, Blazor destrói e recria completamente a seção em vez de tentar atualizar o conteúdo da seção. Ao contrário da renderização normal, o conteúdo da seção pode vir de instâncias diferentes e não faz sentido tentar processar conteúdo de dois componentes separados, o que pode levar a resultados inesperados. Para obter uma explicação detalhada sobre esse comportamento, consulte a inicialização inconsistente de componentes com Blazor SectionOutlet/SectionContent e CascadingValue (dotnet/aspnetcore nº 58316).

Interação da seção com outros Blazor recursos

Uma seção interage com outros Blazor recursos das seguintes maneiras:

• Os valores em cascata fluem para o conteúdo da seção de onde o conteúdo é definido pelo SectionContent componente.
• Exceções não tratadas são tratadas por limites de erro definidos em torno de um SectionContent componente.
• Um Razor componente configurado para renderização de streaming também configura o conteúdo da seção fornecido por um SectionContent componente para usar a renderização de streaming.
• Uma seção que contém componentes interativos é renderizada estaticamente (não funcional) em um componente de layout em um Blazor Web App que adota a renderização por página/componente. Para obter mais informações, consulte ASP.NET Layouts principaisBlazor.