ASP.NET Core Blazor componentes de modelo

Por Robert Haken

Este artigo explica como os componentes de modelo podem aceitar um ou mais modelos de interface do usuário como parâmetros, que podem ser usados como parte da lógica de renderização do componente.

Componentes modelados:

Os componentes de modelo são componentes que recebem um ou mais modelos de interface do usuário como parâmetros, que podem ser utilizados na lógica de renderização do componente. Usando componentes modelados, você pode criar componentes de nível superior que são mais reutilizáveis. Os exemplos incluem:

• Um componente de tabela que permite que um usuário especifique modelos para o cabeçalho, linhas e rodapé da tabela.
• Um componente de lista que permite que um usuário especifique um modelo para renderizar itens em uma lista.
• Um componente da barra de navegação que permite que um usuário especifique um modelo para iniciar conteúdo e links de navegação.

Um componente modelo é definido especificando um ou mais parâmetros de componente do tipo RenderFragment ou RenderFragment<TValue>. Um fragmento de renderização representa um segmento da interface do usuário a ser renderizado. RenderFragment<TValue> usa um parâmetro type que pode ser especificado quando o fragmento de renderização é invocado.

Observação

Para obter mais informações sobre RenderFragment, consulte componentes do ASP.NET Core Razor.

Muitas vezes, os componentes de modelo são genericamente digitados, como o componente a seguir TemplatedNavBar (TemplatedNavBar.razor) demonstra. O tipo genérico (<T>) no exemplo a seguir é usado para renderizar valores IReadOnlyList<T>, que neste caso são uma lista de animais de estimação para um componente que exibe uma barra de navegação com links para um componente de detalhamento de animais de estimação.

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

Ao usar um componente de modelo, os parâmetros do modelo podem ser especificados usando elementos filho que correspondem aos nomes dos parâmetros. No exemplo a seguir, <StartContent>...</StartContent> e <ItemTemplate>...</ItemTemplate> fornecem RenderFragment<TValue> modelos para StartContent e ItemTemplate do componente TemplatedNavBar.

Especifique o Context atributo no elemento do componente quando desejar indicar o nome do parâmetro de conteúdo para conteúdo filho implícito (sem qualquer elemento filho de encapsulamento). No exemplo a seguir, o Context atributo aparece no elemento e se aplica a todos os TemplatedNavBar parâmetros do RenderFragment<TValue> modelo.

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

Como alternativa, você pode alterar o nome do parâmetro usando o Context atributo no RenderFragment<TValue> elemento filho. No exemplo a seguir, o Context é definido em ItemTemplate vez 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; }
    }
}

Os argumentos de componentes do tipo RenderFragment<TValue> têm um parâmetro implícito chamado context, que pode ser usado. No exemplo a seguir, Context não está definido. @context.{PROPERTY} Fornece valores de animais de estimação para o modelo, onde {PROPERTY} é uma propriedade 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; }
    }
}

Ao usar componentes de tipo genérico, o parâmetro type é inferido, se possível. No entanto, você pode especificar explicitamente o tipo com um atributo que tenha um nome correspondente ao parâmetro type, que está TItem no exemplo anterior:

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

O exemplo fornecido no componente TemplatedNavBar (TemplatedNavBar.razor) pressupõe que a coleção Items não muda após a renderização inicial; ou que, se mudar, não é necessário manter o estado dos componentes/elementos utilizados em ItemTemplate. Para componentes de modelo em que esse uso não pode ser antecipado, consulte a seção Preservar relações com @key .

Manter relações com @key

Os componentes com modelo geralmente são usados para renderizar coleções de itens, como tabelas ou listas. Nesses cenários gerais, não podemos supor que o usuário evitará componentes/elementos com estado na definição do template de item ou que não haverá alterações adicionais na coleção Items. Para esses componentes modelados, é necessário preservar as relações com o @key atributo de diretiva.

Observação

Para obter mais informações sobre o @key atributo de diretiva, consulte Reter relações de elemento, componente e modelo no ASP.NET Core Blazor.

O componente a seguir TableTemplate (TableTemplate.razor) demonstra um componente com modelo que preserva as relações com @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!;
}

Considere o seguinte Pets5 componente (Pets5.razor), que demonstra a importância de inserir dados para preservar as relações do modelo. No componente, cada iteração da adição de um animal de estimação em OnAfterRenderAsync resulta na rerenderização do componente em Blazor.

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

Esta demonstração permite-lhe:

• Selecione uma <input> entre várias linhas de tabela renderizadas.
• Estude o comportamento do foco da página à medida que a coleção de animais de estimação cresce automaticamente.

Sem usar o atributo de diretiva @key no componente TableTemplate, o foco da página permanece na mesma posição de índice (linha) da tabela, o que faz com que o foco mude cada vez que um animal de estimação é adicionado. Para demonstrar isso, remova o atributo e o valor da @key diretiva, reinicie o aplicativo e tente modificar um valor de campo à medida que os itens são adicionados.

Recursos adicionais

• ASP.NET Principais Blazor práticas recomendadas de desempenho de renderização
• Reter relações de elementos, componentes e modelos no ASP.NET Core Blazor
• Blazor exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)