Tag Helper de composant dans ASP.NET Core

Le Tag Helper du composant affiche un composant Razor dans une page Pages Razor ou un affichage MVC.

Prérequis

Suivez les instructions fournies dans la section Utiliser des composants non routables dans des pages ou des affichages de l’article Intégrer des composants Razor ASP.NET Core dans des applications ASP.NET Core.

Tag Helper de composant

Pour afficher un composant à partir d’une page ou d’une vue, utilisez le Tag Helper de composant (balise <component>).

RenderMode configure si le composant :

• est prérendu dans la page.
• est rendu en tant que code HTML statique sur la page ou s’il inclut les informations nécessaires pour démarrer une application Blazor à partir de l’agent utilisateur.

Les modes d’affichage d’application Blazor WebAssembly sont présentés dans le tableau suivant.

Mode d’affichage	Description
WebAssembly	Restitue un marqueur pour une application Blazor WebAssembly afin d’inclure un composant interactif lors du chargement dans le navigateur. Le composant n’est pas prédéfini. Cette option facilite l’affichage de différents composants Blazor WebAssembly sur différentes pages.
WebAssemblyPrerendered	Présente le composant au format HTML statique et inclut un marqueur pour une application Blazor WebAssembly pour une utilisation ultérieure afin de rendre le composant interactif lorsqu’il est chargé dans le navigateur.

Les modes d’affichage sont affichés dans le tableau suivant.

Mode d’affichage	Description
ServerPrerendered	Affiche le composant en HTML statique et inclut un marqueur pour une application Blazor côté serveur. Lorsque l’agent utilisateur démarre, ce marqueur est utilisé pour démarrer une application Blazor.
Server	Affiche un marqueur pour une application Blazor côté serveur. La sortie du composant n’est pas incluse. Lorsque l’agent utilisateur démarre, ce marqueur est utilisé pour démarrer une application Blazor.
Static	Affiche le composant en HTML statique.

Les caractéristiques supplémentaires sont les suivantes :

• Plusieurs Tag Helpers de composant qui affichent plusieurs composants Razor sont autorisés.
• Les composants ne peuvent pas être affichés dynamiquement après le démarrage de l’application.
• Bien que les pages et les vues puissent utiliser des composants, l’inverse n’est pas vrai. Les composants ne peuvent pas utiliser des fonctionnalités spécifiques à l’affichage et à la page, telles que les vues partielles et les sections. Pour utiliser la logique d’une vue partielle dans un composant, tenez compte de la logique de vue partielle dans un composant.
• L’affichage des composants serveur à partir d’une page HTML statique n’est pas pris en charge.

Le Tag Helper du composant suivant affiche le composant EmbeddedCounter dans une page ou une vue d’une application Blazor côté serveur avec ServerPrerendered :

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

...

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

L’exemple précédent suppose que le composant EmbeddedCounter se trouve dans le dossier Components de l’application. L’espace réservé {APP ASSEMBLY} est le nom de l’assembly de l’application (par exemple, @using BlazorSample.Components).

Le Tag Helper de composant peut également passer des paramètres aux composants. Considérez le composant ColorfulCheckbox suivant qui définit la couleur et la taille de l’étiquette de case à cocher.

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

Les paramètres de composantSize(int) et Color (string) peuvent être définis par le Tag Helper de composant :

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

...

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

L’exemple précédent suppose que le composant ColorfulCheckbox se trouve dans le dossier Components. L’espace réservé {APP ASSEMBLY} est le nom de l’assembly de l’application (par exemple, @using BlazorSample.Components).

Le code HTML suivant est affiché dans la page ou la vue :

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

La transmission d’une chaîne entre guillemets nécessite une expression Razor explicite, comme indiqué pour param-Color dans l’exemple précédent. Le comportement d’analyse Razor d’une valeur de type string ne s’applique pas à un attribut param-*, car l’attribut est un type object.

Tous les types de paramètres sont pris en charge, à l’exception de :

• Paramètres génériques.
• Paramètres non sérialisables.
• Héritage dans les paramètres de collection.
• Paramètres dont le type est défini en dehors de l’application Blazor WebAssembly ou dans un assembly chargé tardivement.
• Pour recevoir un délégué RenderFragment pour le contenu enfant (par exemple, param-ChildContent="..."). Pour ce scénario, nous recommandons la création d’un composant Razor (.razor) qui fait référence au composant que vous souhaitez afficher avec le contenu enfant que vous souhaitez transmettre, puis d’appeler le composant Razor à partir de la page ou de la vue avec le composant Tag Helper.

Le type de paramètre doit être JSON sérialisable, ce qui signifie généralement que le type doit avoir un constructeur par défaut et des propriétés définissables. Par exemple, vous pouvez spécifier une valeur pour Size et Color dans l’exemple précédent, car les types Size et Color sont des types primitifs (int et string), qui sont pris en charge par le sérialiseur JSON.

Dans l’exemple suivant, un objet de classe est passé au composant :

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

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

La classe doit avoir un constructeur public sans paramètre.

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

L’exemple précédent suppose que le composant ParameterComponent se trouve dans le dossier Components de l’application. L’espace réservé {APP ASSEMBLY} est le nom de l’assembly de l’application (par exemple, @using BlazorSample et @using BlazorSample.Components). MyClass se trouve dans l’espace de noms de l’application.

Ressources supplémentaires

• Conserver le Tag Helper d’état du composant dans ASP.NET Core
• Prérendu des composants Razor ASP.NET Core
• ComponentTagHelper
• Tag Helpers dans ASP.NET Core
• Composants Razor ASP.NET Core