Évitez d'écraser les paramètres dans ASP.NET Core Blazor

Par Robert Haken

Cet article vous explique comment éviter le remplacement des paramètres dans les applications Blazor lors d’un nouveau rendu.

Paramètres remplacés

Le framework Blazor impose généralement une affectation de paramètres parent-enfant sans échec :

• Les paramètres ne sont pas remplacés de manière inattendue.
• Les effets secondaires sont minimisés. Par exemple, les rendus supplémentaires sont évités car ils peuvent créer des boucles de rendu infinies.

Un composant enfant reçoit de nouvelles valeurs de paramètre qui remplacent éventuellement les valeurs existantes lorsque le composant parent est rendu à nouveau. Les valeurs de paramètre dans un composant enfant sont souvent remplacées accidentellement lorsque le composant est développé avec un ou plusieurs paramètres liés aux données et que le développeur écrit directement dans un paramètre de l’enfant :

• Le composant enfant est rendu avec une ou plusieurs valeurs de paramètre du composant parent.
• L’enfant écrit directement dans la valeur d’un paramètre.
• Le composant parent est rendu à nouveau et remplace la valeur du paramètre enfant.

Le risque de remplacement des valeurs de paramètre s’étend également aux accesseurs set de propriété du composant enfant.

Important

Notre conseil général est de ne pas créer de composants qui écrivent directement dans leurs propres paramètres après le rendu initial du composant.

Considérez le composant ShowMoreExpander suivant qui :

• Affiche le titre.
• Affiche le contenu enfant quand il est sélectionné.
• Vous permet de définir l’état initial avec un paramètre de composant (InitiallyExpanded).

Après la démonstration d’un paramètre remplacé avec le composant ShowMoreExpander suivant, un composant ShowMoreExpander modifié présente la bonne approche à suivre dans ce scénario. Les exemples suivants peuvent être placés dans un exemple d’application local pour découvrir les comportements décrits.

ShowMoreExpander.razor:

<div @onclick="ShowMore" class="card bg-light mb-3" style="width:30rem">
    <div class="card-header">
        <h2 class="card-title">Show more (<code>Expanded</code> = @InitiallyExpanded)</h2>
    </div>
    @if (InitiallyExpanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

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

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    private void ShowMore() => InitiallyExpanded = true;
}

Le composant ShowMoreExpander est ajouté au composant parent Expanders suivant qui peut appeler StateHasChanged :

• L’appel de StateHasChanged dans le code du développeur notifie un composant que son état a changé et empile généralement le nouveau rendu du composant pour mettre à jour l’interface utilisateur. Vous trouverez plus de détails sur StateHasChanged plus loin dans le cycle de vie de composant Razor ASP.NET Core et le rendu de composants Razor ASP.NET Core.
• L’attribut de directive @onclick du bouton attache un gestionnaire d’événements à l’événement onclick du bouton. Vous trouverez plus de détails plus loin dans la gestion des événements Blazor ASP.NET Core.

Expanders.razor:

@page "/expanders"

<PageTitle>Expanders</PageTitle>

<h1>Expanders Example</h1>

<ShowMoreExpander InitiallyExpanded="false">
    Expander 1 content
</ShowMoreExpander>

<ShowMoreExpander InitiallyExpanded="false" />

<button @onclick="StateHasChanged">Call StateHasChanged</button>

Au départ, les composants ShowMoreExpander se comportent indépendamment lorsque leurs propriétés InitiallyExpanded sont définies. Les composants enfants conservent leurs états comme prévu.

Si StateHasChanged est appelé dans un composant parent, le framework Blazor regénère le rendu des composants enfants si leurs paramètres ont changé :

• Pour un groupe de types de paramètres que Blazor vérifie explicitement, Blazor regénère le rendu d’un composant enfant s’il détecte que l’un des paramètres a changé.
• Pour les types de paramètres non vérifiés, Blazor regénère le rendu du composant enfant que les paramètres aient changé ou non. Le contenu enfant appartient à cette catégorie de types de paramètres car le contenu enfant est de type RenderFragment, qui est un délégué faisant référence à d’autres objets mutables.

Pour le composant Expanders :

• Le premier composant ShowMoreExpander définit le contenu enfant dans un RenderFragment potentiellement mutable. Un appel à StateHasChanged dans le composant parent regénère donc automatiquement le rendu du composant et remplace potentiellement la valeur de InitiallyExpanded par sa valeur initiale de false.
• Le deuxième composant ShowMoreExpander ne définit pas de contenu enfant. Par conséquent, un RenderFragment potentiellement mutable n’existe pas. Un appel à StateHasChanged dans le composant parent ne regénère pas automatiquement le rendu du composant enfant. La valeur InitiallyExpanded du composant n’est donc pas remplacée.

Pour conserver l’état dans le scénario précédent, utilisez un champ privé dans le composant ShowMoreExpander.

Le composant ShowMoreExpander révisé suivant :

• Accepte la valeur de paramètre de composant InitiallyExpanded du parent.
• Affecte la valeur de paramètre de composant à un champ privé (expanded) dans l’événement OnInitialized.
• Utilise le champ privé pour conserver son état de basculement interne, ce qui montre comment éviter d’écrire directement dans un paramètre.

Remarque

Les conseils de cette section s’appliquent également aux accesseurs set de paramètre de composant, ce qui peut entraîner des effets secondaires indésirables similaires.

ShowMoreExpander.razor:

<div @onclick="Expand" class="card bg-light mb-3" style="width:30rem">
    <div class="card-header">
        <h2 class="card-title">Show more (<code>Expanded</code> = @expanded)</h2>
    </div>
    @if (expanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

@code {
    private bool expanded;

    [Parameter]
    public bool InitiallyExpanded { get; set; }

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    protected override void OnInitialized() => expanded = InitiallyExpanded;

    private void Expand() => expanded = true;
}

Remarque

Le ShowMoreExpander révisé ne reflète pas les modifications apportées au paramètre InitiallyExpanded après l’initialisation (OnInitialized). Dans certains scénarios, un composant déjà initialisé peut recevoir de nouvelles valeurs de paramètre. Cela peut se produire, par exemple, dans une vue principale/subordonnée où le même composant est utilisé pour afficher différentes vues de détails ou lorsque le paramètre de routage /item/{id} change pour afficher un autre élément.

Envisagez le composant ToggleExpander suivant qui :

• Vous permet de changer l’état à la fois de l’intérieur et de l’extérieur.
• Gère de nouvelles valeurs de paramètre même si la même instance de composant est réutilisée.

ToggleExpander.razor:

<div class="card bg-light mb-3" style="width:30rem">
    <div @onclick="Toggle" class="card-header">
        <h2 class="card-title">Toggle (<code>Expanded</code> = @expanded)</h2>
    </div>
    @if (expanded)
    {
        <div class="card-body">
            <p class="card-text">@ChildContent</p>
        </div>
    }
</div>

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

    [Parameter]
    public EventCallback<bool> ExpandedChanged { get; set; }

    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    private bool expanded;

    protected override void OnParametersSet() => expanded = Expanded;

    private async Task Toggle()
    {
        expanded = !expanded;
        await ExpandedChanged.InvokeAsync(expanded);
    }
}

Le composant ToggleExpander doit être utilisé avec la syntaxe de liaison @bind-Expanded="{field}", ce qui permet une synchronisation bidirectionnelle du paramètre.

ExpandersToggle.razor:

@page "/expanders-toggle"

<PageTitle>Expanders Toggle</PageTitle>

<h1>Expanders Toggle</h1>

<ToggleExpander @bind-Expanded="expanded">
    Expander content
</ToggleExpander>

<button @onclick="Toggle">Toggle</button>

<button @onclick="StateHasChanged">Call StateHasChanged</button>

@code {
    private bool expanded;

    private void Toggle() => expanded = !expanded;
}

Pour plus d'informations sur la liaison parent-enfant, voir les ressources suivantes :

• Liaison à des paramètres de composant
• Lier plus de deux composants
• Blazor erreur de liaison bidirectionnelle (dotnet/aspnetcore #24599)

Pour plus d’informations sur la détection des modifications, notamment sur les types exacts vérifiés par Blazor, consultez le rendu de composants Razor ASP.NET Core.