Parâmetros arbitrários e splatting de atributos do Blazor ASP.NET Core

Os componentes podem capturar e renderizar atributos adicionais além dos parâmetros e campos declarados do componente. Atributos adicionais podem ser capturados em um dicionário e então aplicados a um elemento, chamado nivelamento quando o componente é renderizado usando o atributo de diretiva @attributesRazor. Esse cenário é útil para definir um componente que produz um elemento de marcação com suporte para uma variedade de personalizações. Por exemplo, pode ser entediante definir atributos separadamente para um <input> que dá suporte a muitos parâmetros ou campos.

Splatting do atributo

No seguinte componente Splat:

• O primeiro <input> elemento (id="useIndividualParams") usa campos de componente individuais.
• O segundo elemento <input> (id="useAttributesDict") usa nivelamento de atributo.

Splat.razor:

@page "/splat"

<PageTitle>SPLAT!</PageTitle>

<h1>Splat Parameters Example</h1>

<input id="useIndividualParams"
       maxlength="@maxlength"
       placeholder="@placeholder"
       required="@required"
       size="@size" />

<input id="useAttributesDict"
       @attributes="InputAttributes" />

@code {
    private string maxlength = "10";
    private string placeholder = "Input placeholder text";
    private string required = "required";
    private string size = "50";

    private Dictionary<string, object> InputAttributes { get; set; } =
        new()
        {
            { "maxlength", "10" },
            { "placeholder", "Input placeholder text" },
            { "required", "required" },
            { "size", "50" }
        };
}

Com exceção de id, os elementos renderizados <input> na página da web têm atributos idênticos:

<input id="useIndividualParams"
       maxlength="10"
       placeholder="Input placeholder text"
       required="required"
       size="50">

<input id="useAttributesDict"
       maxlength="10"
       placeholder="Input placeholder text"
       required="required"
       size="50">

Embora o exemplo anterior use campos para o primeiro <input> elemento (id="useIndividualParams"), o mesmo comportamento se aplica quando parâmetros de componente são usados.

Atributos arbitrários

Para aceitar atributos arbitrários, defina um parâmetro de componente com a propriedade CaptureUnmatchedValues definida como true:

@code {
    [Parameter(CaptureUnmatchedValues = true)]
    public Dictionary<string, object>? InputAttributes { get; set; }
}

A propriedade CaptureUnmatchedValues em [Parameter] permite que o parâmetro faça a correspondência com todos os atributos que não correspondem a nenhum outro parâmetro. Um componente só pode definir um parâmetro com CaptureUnmatchedValues. O tipo de propriedade usado com CaptureUnmatchedValues deve ser atribuível com base em Dictionary<string, object> com chaves de cadeia de caracteres. O uso de IEnumerable<KeyValuePair<string, object>> ou IReadOnlyDictionary<string, object> também são opções neste cenário.

A posição de @attributes em relação à posição dos atributos de elemento é importante. Quando @attributes são aplicados no elemento renderizado, os atributos são processados da direita para a esquerda (do último para o primeiro), com o primeiro atributo tendo precedência sobre quaisquer atributos comuns. Considere o exemplo a seguir de um componente pai que consome um componente filho, em que o filho define um atributo "extra" e o componente pai esbanja um atributo "extra" no componente filho.

AttributeOrderChild1.razor:

<div @attributes="AdditionalAttributes" extra="5" />

@code {
    [Parameter(CaptureUnmatchedValues = true)]
    public IDictionary<string, object>? AdditionalAttributes { get; set; }
}

AttributeOrder1.razor:

@page "/attribute-order-1"

<PageTitle>Attribute Order 1</PageTitle>

<h1>Attribute Order Example 1</h1>

<AttributeOrderChild1 extra="10" />

<p>
    View the HTML markup in your browser to inspect the attributes on
    the AttributeOrderChild1 component.
</p>

O atributo AttributeOrderChild1 do componente extra é definido à direita de @attributes. O AttributeOrderParent1 renderizado do componente <div> contém extra="5" quando passado pelo atributo adicional porque os atributos são processados da direita para a esquerda (último a primeiro), sendo que o primeiro atributo "extra" prevalece, que é o atributo HTML codificado extra do componente AttributeOrderParent1.

<div extra="5" />

No exemplo a seguir, a ordem de extra e @attributes é invertida no componente filho <div>. Nesse cenário, o componente AttributeOrderParent2 tem o <div> renderizado que contém extra="10" ao passar pelo atributo adicional, porque o primeiro atributo "extra" processado é o atributo HTML "nivelado" extra do componente pai.

AttributeOrderChild2.razor:

<div extra="5" @attributes="AdditionalAttributes" />

@code {
    [Parameter(CaptureUnmatchedValues = true)]
    public IDictionary<string, object>? AdditionalAttributes { get; set; }
}

AttributeOrder2.razor:

@page "/attribute-order-2"

<PageTitle>Attribute Order 2</PageTitle>

<h1>Attribute Order Example 2</h1>

<AttributeOrderChild2 extra="10" />

<p>
    View the HTML markup in your browser to inspect the attributes on
    the AttributeOrderChild2 component.
</p>

A <div> na página da Web renderizada do componente pai contém extra="10":

<div extra="10" />