Evitar a substituição de parâmetros no ASP.NET Core Blazor

Por Robert Haken

Este artigo explica como evitar a substituição de parâmetros nos aplicativos Blazor durante a renderização.

Parâmetros substituídos

A estrutura Blazor geralmente impõe uma atribuição segura de parâmetro pai para filho:

• Os parâmetros não são substituídos inesperadamente.
• Os efeitos colaterais são minimizados. Por exemplo, renderizações adicionais são evitadas porque podem criar loops de renderização infinitos.

Um componente filho recebe novos valores de parâmetro que possivelmente substituem valores existentes quando o componente pai é renderizado novamente. A substituição acidental de valores de parâmetro em um componente filho geralmente ocorre ao desenvolver o componente com um ou mais parâmetros associados a dados, quando o desenvolvedor grava diretamente em um parâmetro no filho:

• O componente filho é renderizado com um ou mais valores de parâmetro do componente pai.
• O filho grava diretamente no valor de um parâmetro.
• O componente pai é renderizado novamente e substitui o valor do parâmetro filho.

O potencial de substituição de valores de parâmetro também se estende aos acessadores da propriedade set do componente filho.

Importante

Nossa diretriz geral é de não criar componentes que gravam diretamente nos próprios parâmetros depois que o componente é renderizado pela primeira vez.

Considere o seguinte componente ShowMoreExpander que:

• Renderiza o título.
• Mostra o conteúdo filho quando selecionado.
• Permite que você defina o estado inicial com um parâmetro de componente (InitiallyExpanded).

Depois que o componente ShowMoreExpander a seguir demonstra um parâmetro substituído, um componente ShowMoreExpander modificado é mostrado para demonstrar a abordagem correta para esse cenário. Os exemplos a seguir podem ser colocados em um aplicativo de exemplo local para experimentar os comportamentos descritos.

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

O componente ShowMoreExpander é adicionado ao seguinte componente pai Expanders que pode chamar StateHasChanged:

• Chamar StateHasChanged no código do desenvolvedor notifica um componente de que seu estado foi alterado e normalmente enfileira a nova renderização do componente para atualizar a interface do usuário. StateHasChanged será abordado com mais detalhes posteriormente em Ciclo de vida de componentes Razor no ASP.NET Core e Renderização de componentes Razor no ASP.NET Core.
• O atributo de diretiva do botão @onclick anexa um manipulador de eventos ao evento onclick do botão. A manipulação de eventos será abordada com mais detalhes posteriormente em Manipulação de eventos de Blazor no 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>

Inicialmente, os componentes ShowMoreExpander se comportam de forma independente quando suas propriedades InitiallyExpanded são definidas. Os componentes filho mantêm seus estados, conforme o esperado.

Se StateHasChanged for chamado em um componente pai, a estrutura Blazor renderizará novamente os componentes filho se os parâmetros deles puderem ter sido alterados:

• Para um grupo de tipos de parâmetro que Blazor verifica explicitamente, Blazor renderiza novamente um componente filho quando detecta que qualquer um dos parâmetros foi alterado.
• Para tipos de parâmetro não verificados, Blazor renderiza novamente o componente filho independentemente de os parâmetros terem sido alterados. O conteúdo filho se enquadra nessa categoria de tipos de parâmetro porque é do tipo RenderFragment, que é um delegado que se refere a outros objetos mutáveis.

Para o componente Expanders:

• O primeiro componente ShowMoreExpander define o conteúdo filho em um valor potencialmente mutável RenderFragment, portanto, uma chamada para StateHasChanged no componente pai renderiza novamente, de maneira automática, o componente e potencialmente substitui o valor de InitiallyExpanded para seu valor inicial de false.
• O segundo componente ShowMoreExpander não define o conteúdo filho. Portanto, um RenderFragment potencialmente mutável não existe. Uma chamada para StateHasChanged no componente pai não renderiza novamente, de maneira automática, o componente filho, portanto o valor do componente InitiallyExpanded não é substituído.

Para manter o estado no cenário anterior, use um campo privado no componente ShowMoreExpander para manter seu estado.

O seguinte componente ShowMoreExpander revisado:

• Aceita o valor do parâmetro de componente InitiallyExpanded do pai.
• Atribui o valor do parâmetro de componente a um campo privado (expanded) no evento OnInitialized.
• Usa o campo privado para manter o estado de alternância interno, que demonstra como evitar gravar diretamente em um parâmetro.

Observação

A orientação nesta seção se estende à lógica semelhante em acessadores set de parâmetro de componente, o que pode resultar em efeitos colaterais indesejáveis semelhantes.

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

Observação

O ShowMoreExpander revisado não reflete as alterações no parâmetro InitiallyExpanded após a inicialização (OnInitialized). Em determinados cenários, um componente já inicializado pode receber novos valores de parâmetros. Isso pode acontecer, por exemplo, em uma exibição de principal-subordinado na qual o mesmo componente é usado para renderizar diferentes exibições de detalhes ou quando o parâmetro da rota /item/{id} é alterado para exibir um item diferente.

Considere o seguinte componente ToggleExpander que:

• Permite que você altere o estado tanto de dentro quanto de fora.
• Trata os novos valores de parâmetros mesmo que a mesma instância de componente seja reutilizada.

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 void Toggle()
    {
        expanded = !expanded;
        await ExpandedChanged.InvokeAsync(expanded);
    }
}

O componente ToggleExpander deve ser usado com a sintaxe de associação @bind-Expanded="{field}", permitindo a sincronização bidirecional do parâmetro.

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

Para obter mais informações sobre associação pai-filho, confira os seguintes recursos:

• Associação com parâmetros de componentes
• Associação de mais de dois componentes
• Blazor Erro de Associação Bidirecional (dotnet/aspnetcore #24599)

Para obter mais informações sobre a detecção de alterações, incluindo informações sobre os tipos exatos que Blazor verifica, consulte Renderização de componentes de Razor ASP.NET Core.