Componentes con plantilla de Blazor en ASP.NET Core

Por Robert Haken

En este artículo se explica cómo los componentes con plantilla pueden aceptar una o varias plantillas de interfaz de usuario como parámetros, que se pueden usar como parte de la lógica de representación del componente.

Componentes con plantilla

Los componentes con plantilla son componentes que reciben una o varias plantillas de interfaz de usuario como parámetros, que se pueden usar en la lógica de representación del componente. Mediante el uso de componentes con plantilla, puede crear componentes de nivel superior que sean más reutilizables. Algunos ejemplos son:

• Un componente de tabla que permite a un usuario especificar plantillas para el encabezado, las filas y el pie de página de la tabla.
• Un componente de lista que permite a un usuario especificar una plantilla para representar elementos en una lista.
• Componente de barra de navegación que permite a un usuario especificar una plantilla para iniciar contenido y vínculos de navegación.

Un componente con plantilla se define especificando uno o más parámetros de componente de tipo RenderFragment o RenderFragment<TValue>. Un fragmento de representación representa un segmento de interfaz de usuario que se va a representar. RenderFragment<TValue> toma un parámetro de tipo que se puede especificar cuando se invoca el fragmento de representación.

Nota

Para obtener más información sobre RenderFragment, consulte Componentes de Razor de ASP.NET Core.

A menudo, los componentes con plantilla tienen un tipo genérico, como se muestra en el siguiente componente de TemplatedNavBar (TemplatedNavBar.razor). El tipo genérico (<T>) del ejemplo siguiente se usa para representar valores de IReadOnlyList<T>, que en este caso es una lista de mascotas para un componente que muestra una barra de navegación con vínculos a un componente de detalles de mascotas.

TemplatedNavBar.razor:

@typeparam TItem

<nav class="navbar navbar-expand navbar-light bg-light">
    <div class="container justify-content-start">
        @StartContent
        <div class="navbar-nav">
            @foreach (var item in Items)
            {
                @ItemTemplate(item)
            }
        </div>
    </div>
</nav>

@code {
    [Parameter]
    public RenderFragment? StartContent { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> ItemTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Al usar un componente con plantilla, los parámetros de plantilla se pueden especificar utilizando los elementos secundarios que coinciden con los nombres de los parámetros. En el ejemplo siguiente, <StartContent>...</StartContent> y <ItemTemplate>...</ItemTemplate> proporcionan plantillas de RenderFragment<TValue> para StartContent y ItemTemplate del componente TemplatedNavBar.

Especifique el atributo Context en el elemento de componente si quiere especificar el nombre del parámetro de contenido para el contenido secundario implícito (sin ningún elemento secundario de ajuste). En el ejemplo siguiente, el atributo Context aparece en el elemento TemplatedNavBar y se aplica a todos los parámetros RenderFragment<TValue> de la plantilla.

Pets1.razor:

@page "/pets-1"

<PageTitle>Pets 1</PageTitle>

<h1>Pets Example 1</h1>

<TemplatedNavBar Items="pets" Context="pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-1")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Como alternativa, puede cambiar el nombre del parámetro mediante el atributo Context en el elemento secundario RenderFragment<TValue>. En el ejemplo siguiente, Context se establece en ItemTemplate en lugar de en TemplatedNavBar.

Pets2.razor:

@page "/pets-2"

<PageTitle>Pets 2</PageTitle>

<h1>Pets Example 2</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate Context="pet">
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-2")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Los argumentos de componente de tipo RenderFragment<TValue> tienen un parámetro implícito denominado context que se puede usar. En el ejemplo siguiente, no se ha establecido Context. @context.{PROPERTY} proporciona valores de mascotas a la plantilla, donde {PROPERTY} es una propiedad de Pet:

Pets3.razor:

@page "/pets-3"

<PageTitle>Pets 3</PageTitle>

<h1>Pets Example 3</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{context.PetId}?ReturnUrl=%2Fpets-3")" class="nav-link">
            @context.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Al usar componentes de tipo genérico, el parámetro de tipo se infiere, si es posible. Sin embargo, puede especificar explícitamente el tipo con un atributo que tenga un nombre que coincida con el parámetro de tipo, que es TItem en el ejemplo anterior:

Pets4.razor:

@page "/pets-4"

<PageTitle>Pets 4</PageTitle>

<h1>Pets Example 4</h1>

<TemplatedNavBar Items="pets" Context="pet" TItem="Pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-4")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 2, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 4, Name = "Salem Saberhagen" },
        new Pet { PetId = 7, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

El ejemplo proporcionado en el componente TemplatedNavBar (TemplatedNavBar.razor) supone que la colección Items no cambia tras la representación inicial; o que si cambia, no es necesario mantener el estado de los componentes/elementos usados en ItemTemplate. Para los componentes con plantilla en los que no se puede prever este uso, consulte la sección Conservar relaciones con @key.

Conservar relaciones con @key

Los componentes con plantilla se suelen usar para representar colecciones de elementos, como tablas o listas. En estos escenarios generales, no podemos suponer que el usuario evitará componentes o elementos con estado en la definición de plantilla de elemento o que no habrá cambios adicionales en la colección Items. Para estos componentes con plantilla, es necesario conservar las relaciones con el atributo de directiva @key.

Nota:

Para más información sobre el atributo de directiva @key, consulte Relaciones entre elementos, componentes y modelos en ASP.NET Core Blazor.

El siguiente componente de TableTemplate (TableTemplate.razor) muestra un componente con plantilla que conserva las relaciones con @key.

TableTemplate.razor:

@typeparam TItem

<table class="table">
    <thead>
        <tr>@TableHeader</tr>
    </thead>
    <tbody>
        @foreach (var item in Items)
        {
            <tr @key="@item">@RowTemplate(item)</tr>
        }
    </tbody>
</table>

@code {
    [Parameter]
    public RenderFragment? TableHeader { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> RowTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Considere el siguiente componente Pets5 (Pets5.razor), que demuestra la importancia de asignar claves a los datos para preservar las relaciones del modelo. En el componente, cada iteración de añadir una mascota en OnAfterRenderAsync da como resultado que Blazor vuelva a representar el componente TableTemplate.

Pets5.razor:

@page "/pets-5"

<PageTitle>Pets 5</PageTitle>

<h1>Pets Example 5</h1>

<TableTemplate Items="pets" Context="pet">
    <TableHeader>
        <th>ID</th>
        <th>Name</th>
    </TableHeader>
    <RowTemplate>
        <td><input value="@pet.PetId" /></td>
        <td><input value="@pet.Name" /></td>
    </RowTemplate>
</TableTemplate>


@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Insert new pet every 5 seconds
        if (pets.Count < 10)
        {
            await Task.Delay(5000);
            pets.Insert(0, new Pet() { PetId = pets.Count + 1, Name = "<new pet>" });
            StateHasChanged();
        }
    }

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Esta demostración le permite:

• Seleccione un <input> de entre varias filas de tabla representadas.
• Estudie el comportamiento del foco de la página a medida que crece automáticamente la colección de mascotas.

Si no usa el atributo de directiva @key en el componente TableTemplate, el foco de la página permanece en la misma posición de índice (fila) de la tabla, lo que provoca que el foco se desplace cada vez que se agrega una mascota. Para demostrarlo, elimine el atributo y el valor de la directiva @key, reinicie la aplicación e intente modificar el valor de un campo a medida que se agregan elementos.

Recursos adicionales

• Procedimientos recomendados de rendimiento de Blazor en ASP.NET Core
• Conservación de las relaciones de elementos, componentes y modelos en ASP.NET Core Blazor
• Repositorio de GitHub con ejemplos de Blazor (dotnet/blazor-samples) (cómo descargar)