Auxiliar de Marca de Componente no ASP.NET Core

O Auxiliar de Marca de Componente renderiza um componente Razor em uma página do Razor Pages ou em uma exibição do MVC.

Pré-requisitos

Siga as diretrizes na seção Usar componentes não roteáveis em páginas ou exibições do artigo Integrar componentes ASP.NET Core Razor em aplicativos ASP.NET Core.

Auxiliar de Marcação de componente

Para renderizar um componente em uma página ou exibição, use o Auxiliar de Marcação de Componentes (marcação <component>).

RenderMode configura-se quando o componente:

• É pré-renderizado na página.
• É renderizado como HTML estático na página ou se as informações necessárias para inicializar um Blazor aplicativo do agente do usuário estão inclusas.

Os modos de renderização do aplicativo Blazor WebAssembly são mostrados na tabela abaixo.

Modo de Renderização	Descrição
WebAssembly	Renderiza um marcador para um aplicativo Blazor WebAssembly a ser usado para incluir um componente interativo quando carregado no navegador. O componente não é pré-renderizado. Essa opção facilita a renderização de diferentes componentes Blazor WebAssembly em páginas diferentes.
WebAssemblyPrerendered	Pré-renderiza o componente em HTML estático e inclui um marcador para um aplicativo Blazor WebAssembly para uso posterior, a fim de tornar o componente interativo quando carregado no navegador.

Os modos de renderização são mostrados na tabela a seguir.

Modo de Renderização	Descrição
ServerPrerendered	Renderiza o componente em HTML estático e inclui um marcador para um aplicativo Blazor no servidor. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.
Server	Renderiza um marcador para um aplicativo Blazor no servidor. A saída do componente não está incluída. Quando o agente do usuário é iniciado, esse marcador é usado para inicializar um aplicativo Blazor.
Static	Renderiza o componente em HTML estático.

As características adicionais incluem:

• Vários Auxiliares de Marca de Componentes com renderização de vários componentes Razorsão permitidos.
• Os componentes não podem ser renderizados dinamicamente após o início do aplicativo.
• Embora as páginas e exibições possam usar componentes, o inverso não é verdadeiro. Os componentes não podem usar recursos específicos de exibição e de página, como exibições parciais e seções. Para usar a lógica de uma exibição parcial em um componente, considere a lógica de exibição parcial em um componente.
• Não há suporte para a renderização de componentes do servidor a partir de uma página HTML estática.

O seguinte Auxiliar de Marcação de Componentes renderiza o componente EmbeddedCounter em uma página ou exibição em um aplicativo Blazor no servidor com ServerPrerendered:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

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

O exemplo anterior considera que o componente EmbeddedCounter se encontra na pasta Components do aplicativo. O espaço reservado {APP ASSEMBLY} é o nome do assembly do aplicativo (por exemplo, @using BlazorSample.Components).

O Auxiliar de Marcação de Componentes também pode passar parâmetros para os componentes. Considere o componente ColorfulCheckbox a seguir que define a cor e o tamanho do rótulo da caixa de seleção.

Components/ColorfulCheckbox.razor:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string? Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

Os parâmetros de componenteSize(int) e Color (string) podem ser definidos pelo Auxiliar de Marcação de Componentes:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

O exemplo anterior considera que o componente ColorfulCheckbox se encontra na pasta Components. O espaço reservado {APP ASSEMBLY} é o nome do assembly do aplicativo (por exemplo, @using BlazorSample.Components).

O seguinte HTML é renderizado na página ou exibição:

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

A passagem de uma cadeia de caracteres entre aspas requer uma expressão Razor explícita, conforme mostrado em param-Color do exemplo anterior. O comportamento de análise Razor de um valor de tipo string não se aplica a um atributo param-* porque o atributo é um tipo object.

Todos os tipos de parâmetros são compatíveis, exceto:

• Parâmetros genéricos.
• Parâmetros não serializáveis.
• Herança de parâmetros de coleção.
• Parâmetros cujo tipo é definido fora do aplicativo Blazor WebAssembly ou em um assembly carregado lentamente.
• Para receber um delegado RenderFragment para o conteúdo filho (por exemplo, param-ChildContent="..."). Para esse cenário, recomendamos a criação de um componente Razor (.razor) que faça referência ao componente que você deseja renderizar com o conteúdo filho que deseja passar e, em seguida, invoque o componente Razor da página ou exibição com o Auxiliar de Marcação de Componentes.

O tipo de parâmetro deve ser JSON serializável, o que normalmente significa que o tipo deve ter um construtor padrão e propriedades configuráveis. Por exemplo, você pode especificar um valor para Size e Color no exemplo anterior porque os tipos de Size e Color são tipos primitivos (int e string), que são compatíveis com o serializador JSON.

No exemplo a seguir, um objeto de classe é passado para o componente:

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

A classe deve ter um construtor público sem parâmetros.

Components/ParameterComponent.razor:

<h2>ParameterComponent</h2>

<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>

@code
{
    [Parameter]
    public MyClass? MyObject { get; set; }
}

Pages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Components

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

O exemplo anterior considera que o componente ParameterComponent se encontra na pasta Components do aplicativo. O espaço reservado {APP ASSEMBLY} é o nome do assembly do aplicativo (por exemplo, @using BlazorSample e @using BlazorSample.Components). MyClass está no namespace do aplicativo.

Recursos adicionais

• Persistir o Auxiliar de Marca de Estado de Componente no ASP.NET Core
• Pré-renderização de componentes Razor do ASP.NET Core
• ComponentTagHelper
• Auxiliares de Marca no ASP.NET Core
• Componentes Razor no ASP.NET Core