Composants Blazor basés sur un modèle ASP.NET Core

Par Robert Haken

Cet article explique comment les composants basés sur un modèle peuvent accepter un ou plusieurs modèles d’interface utilisateur en tant que paramètres, qui peuvent ensuite être utilisés dans le cadre de la logique de rendu du composant.

Composants basés sur un modèle

Les composants basés sur un modèle sont des composants recevant un ou plusieurs modèles d’interface utilisateur en tant que paramètres qui peuvent ensuite être utilisés dans le cadre de la logique de rendu du composant. En utilisant des composants basés sur un modèle, vous pouvez créer des composants réutilisables et de niveau supérieur. Voici quelques exemples :

• Un composant de tableau qui permet à un utilisateur de spécifier des modèles pour l’en-tête, les lignes et le pied de page de la table.
• Un composant de liste qui permet à un utilisateur de spécifier un modèle pour le rendu d’éléments dans une liste.
• Un composant de barre de navigation qui permet à l’utilisateur de spécifier un modèle pour un contenu initial et des liens de navigation.

Un composant basé sur un modèle est défini en spécifiant un ou plusieurs paramètres de composant de type RenderFragment ou RenderFragment<TValue>. Un fragment de rendu représente un segment de l’interface utilisateur à afficher. RenderFragment<TValue> prend un paramètre de type qui peut être spécifié lorsque le fragment de rendu est invoqué.

Remarque

Pour plus d’informations sur RenderFragment, consultez Composants ASP.NET Core Razor.

Souvent, les composants basés sur un modèle sont typés de façon générique, comme le montre le composant TemplatedNavBar (TemplatedNavBar.razor) suivant. Le type générique (<T>) dans l’exemple suivant est utilisé pour afficher des valeurs de IReadOnlyList<T>, qui correspondent dans ce cas à une liste d’animaux de compagnie pour un composant qui affiche une barre de navigation avec des liens vers un composant pour les détails d’un animal.

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

Lorsque vous utilisez un composant modèle, les paramètres de modèle peuvent être spécifiés à l’aide d’éléments enfants qui correspondent aux noms des paramètres. Dans l’exemple suivant, <StartContent>...</StartContent> et <ItemTemplate>...</ItemTemplate> fournissent des modèles RenderFragment<TValue> pour StartContent et ItemTemplate du composant TemplatedNavBar.

Spécifiez l’attribut Context sur l’élément composant lorsque vous souhaitez spécifier le nom du paramètre de contenu pour le contenu enfant implicite (sans élément enfant d’enveloppement). Dans l’exemple suivant, l’attribut Context s’affiche sur l’élément TemplatedNavBar et s’applique à tous les paramètres de modèle RenderFragment<TValue>.

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

Vous pouvez également modifier le nom du paramètre à l’aide de l’attribut Context sur l’élément enfant RenderFragment<TValue>. Dans l’exemple suivant, le Context est défini sur ItemTemplate au lieu de 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; }
    }
}

Les arguments de composant de type RenderFragment<TValue> ont un paramètre implicite nommé context, qui peut être utilisé. Dans l’exemple suivant, Context n’est pas défini. @context.{PROPERTY} fournit des valeurs pour animaux au modèle, où {PROPERTY} est une propriété 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; }
    }
}

Lorsque vous utilisez des composants de type générique, le paramètre de type est déduit si possible. Toutefois, vous pouvez spécifier explicitement le type avec un attribut qui a un nom correspondant au paramètre de type, qui est TItem dans l’exemple précédent :

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

L’exemple fourni dans le composant TemplatedNavBar (TemplatedNavBar.razor) suppose que la collection Items ne change pas après l’affichage initial ; si elle change, conserver l’état des composants/éléments utilisés dans ItemTemplate n’est pas nécessaire. Pour les composants basés sur un modèle où cette utilisation ne peut pas être anticipée, consultez la section Conserver les relations avec @key.

Conserver les relations avec @key

Les composants basés sur un modèle sont souvent utilisés pour afficher des collections d’éléments, comme des tableaux ou des listes. Dans de tels scénarios d’ordre général, nous ne pouvons pas supposer que l’utilisateur va éviter les composants/éléments avec état dans la définition du modèle d’élément ou qu’il n’y aura pas de modifications supplémentaires apportées à la collection Items. Pour ces composants basés sur un modèle, il est nécessaire de conserver les relations avec l’attribut de directive @key.

Remarque

Pour plus d’informations sur l’attribut de directive @key, consultez Conserver les relations des éléments, des composants et des modèles dans ASP.NET Core Blazor.

Le composant TableTemplate suivant (TableTemplate.razor) illustre un composant basé sur un modèle qui conserve les relations avec @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!;
}

Considérez le composant Pets5 suivant (Pets5.razor), qui illustre l’importance d’utiliser une clé pour les données afin de préserver les relations du modèle. Dans le composant, chaque itération d’ajout d’un animal de compagnie dans OnAfterRenderAsync fait que Blazor réaffiche le composant 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; }
    }
}

Cette démonstration vous permet de :

• Sélectionnez un <input> parmi plusieurs lignes affichées du tableau.
• Examinez le comportement du focus de la page à mesure que la collection d’animaux de compagnie augmente automatiquement.

Si l’attribut de directive @key n’est pas présent dans le composant TableTemplate, le focus de la page reste sur la même position (ligne) d’index du tableau, ce qui provoque le déplacement du focus chaque fois qu’un animal de compagnie est ajouté. Pour illustrer cela, supprimez l’attribut de directive @key et sa valeur, redémarrez l’application, puis essayez de modifier la valeur d’un champ à mesure que des éléments sont ajoutés.

Ressources supplémentaires

• Meilleures pratiques d’ASP.NET Core Blazor en matière de performances
• Conserver les relations entre éléments, composants et modèles dans ASP.NET Core Blazor
• Blazor exemples du référentiel GitHub (dotnet/blazor-samples) (procédure de téléchargement)