Asistente de etiquetas de componente en ASP.NET Core

El asistente de etiquetas del componente representa un componente Razor en una página Razor de Pages o en una vista MVC.

Requisitos previos

Siga las indicaciones de la sección Uso de componentes no enrutables en páginas o vistas del artículo Integración de componentes ASP.NET Core Razor en aplicaciones de ASP.NET Core.

Asistente de etiquetas de componente

Para representar un componente a partir de una página o vista, use el asistente de etiqueta de componente (etiqueta de <component>).

RenderMode configura si el componente:

• Se representa previamente en la página.
• Se representa como HTML estático en la página o si incluye la información necesaria para arrancar una aplicación Blazor desde el agente de usuario.

Los modos de representación de la aplicación Blazor WebAssembly se muestran en la tabla siguiente.

Modo de representación	Descripción
WebAssembly	representa un marcador para una aplicación Blazor WebAssembly, a fin de utilizarlo para incluir un componente interactivo cuando se carga en el explorador. El componente no está representado previamente. Esta opción facilita la representación de diferentes componentes Blazor WebAssembly en páginas distintas.
WebAssemblyPrerendered	representa previamente el componente en HTML estático e incluye un marcador para una aplicación Blazor WebAssembly, a fin de utilizarlo para que el componente sea interactivo cuando se carga en el explorador.

Los modos de representación se muestran en la tabla siguiente.

Modo de representación	Descripción
ServerPrerendered	Representa el componente en HTML estático e incluye un marcador para una aplicación de Blazor del lado servidor. Cuando se inicia el agente de usuario, este marcador se usa para arrancar una aplicación Blazor.
Server	Representa un marcador para una aplicación de Blazor del lado servidor. La salida del componente no está incluida. Cuando se inicia el agente de usuario, este marcador se usa para arrancar una aplicación Blazor.
Static	Representa el componente en HTML estático.

Entre las características adicionales se incluyen las siguientes:

• Se permiten varios asistentes de etiquetas de componentes que representan varios componentes de Razor.
• Los componentes no se pueden representar dinámicamente una vez iniciada la aplicación.
• Mientras que las páginas y las vistas pueden utilizar componentes, lo contrario no es cierto. Los componentes no pueden usar características específicas de página y de vista, tales como vistas y secciones parciales. Para usar la lógica de una vista parcial en un componente, factorice la lógica de vista parcial en un componente.
• No se admite la representación de componentes de servidor desde una página HTML estática.

El asistente de etiquetas de componentes siguiente representa el componente de EmbeddedCounter en una página o vista en una aplicación de Blazor del lado servidor con ServerPrerendered:

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

...

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

En el ejemplo anterior se supone que el componente de EmbeddedCounter está en la carpeta Components de la aplicación. El marcador de posición {APP ASSEMBLY} es el nombre de ensamblado de la aplicación (por ejemplo, @using BlazorSample.Components).

El asistente de etiqueta de componente también puede pasar parámetros a los componentes. Considere el siguiente componente de ColorfulCheckbox que establece el color y el tamaño de la etiqueta de casilla.

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

Los parámetros del componenteSize (int) y Color (string) se pueden establecer mediante el asistente de etiqueta de componente:

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

...

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

En el ejemplo anterior se supone que el componente ColorfulCheckbox está en la carpeta Components. El marcador de posición {APP ASSEMBLY} es el nombre de ensamblado de la aplicación (por ejemplo, @using BlazorSample.Components).

El código HTML siguiente se representa en la página o vista:

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

Pasar una cadena entre comillas requiere una expresión de Razor explícita, como se muestra para el param-Color en el ejemplo anterior. El comportamiento de análisis de Razor de un valor de tipo string no se aplica a un atributo param-* porque el atributo es un tipo object.

Se admiten todos los tipos de parámetros, excepto:

• Parámetros genéricos.
• Parámetros no serializables.
• Herencia en parámetros de colección.
• Parámetros cuyo tipo se define fuera de la aplicación Blazor WebAssembly o dentro de un ensamblado cargado de forma diferida.
• Para recibir un delegado RenderFragment para contenido secundario (por ejemplo, param-ChildContent="..."). Para este escenario, se recomienda crear un componente Razor (.razor) que haga referencia al componente que desea representar con el contenido secundario que desea pasar y, después, invocar el componente Razor desde la página o vista con el asistente de etiqueta de componente.

El tipo de parámetro debe ser JSON serializable, lo que normalmente significa que el tipo debe tener un constructor predeterminado y propiedades configurables. Por ejemplo, puede especificar un valor para Size y Color en el ejemplo anterior porque los tipos de Size y Color son tipos primitivos (int y string), que son compatibles con el serializador JSON.

En el ejemplo siguiente, se pasa un objeto de clase al componente :

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

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

La clase debe tener un constructor sin parámetros público.

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

En el ejemplo anterior se supone que el componente ParameterComponent está en la carpeta Components de la aplicación. El marcador de posición {APP ASSEMBLY} es el nombre de ensamblado de la aplicación (por ejemplo, @using BlazorSample y @using BlazorSample.Components). MyClass está en el espacio de nombres de la aplicación.

Recursos adicionales

• Asistente de etiquetas de conservación del estado del componente en ASP.NET Core
• Representación previa de componentes de Razor de ASP.NET Core
• ComponentTagHelper
• Asistentes de etiquetas en ASP.NET Core
• Componentes Razor de ASP.NET Core