Auxiliar de marca parcial no ASP.NET Core

Artigo
11/30/2023

Para ter uma visão geral dos Auxiliares de Marcação, confira Auxiliares de Marcação no ASP.NET Core.

Exibir ou baixar código de exemplo (como baixar)

Visão geral

O Auxiliar de Marca Parcial é usado para renderizar uma exibição parcial em Razor Pages e em aplicativos MVC. Considere que ele:

Exige o ASP.NET Core 2.1 ou posterior.
É uma alternativa à sintaxe do HTML Helper.
Renderiza a exibição parcial de forma assíncrona.

As opções do HTML Helper para renderizar uma exibição parcial incluem:

O modelo Product é usado nos exemplos ao longo deste documento:

namespace TagHelpersBuiltIn.Models
{
    public class Product
    {
        public int Number { get; set; }

        public string Name { get; set; }

        public string Description { get; set; }
    }
}

Segue um inventário dos atributos do auxiliar de marca parcial.

name

O atributo name é necessário. Indica o nome ou o caminho da exibição parcial a ser renderizada. Quando é fornecido um nome de exibição parcial, o processo descoberta de exibição é iniciado. Esse processo é ignorado quando um caminho explícito é fornecido. Para todos os valores de name aceitáveis, consulte Descoberta de exibição parcial.

A marcação a seguir usa um caminho explícito, indicando que _ProductPartial.cshtml deve ser carregado da pasta Compartilhado. Usando o atributo for, um modelo é passado para a exibição parcial para associação.

<partial name="Shared/_ProductPartial.cshtml" for="Product">

for

O atributo for atribui um ModelExpression a ser avaliado em relação ao modelo atual. Uma ModelExpression infere a sintaxe @Model.. Por exemplo, for="Product" pode ser usado em vez de for="@Model.Product". Esse comportamento de inferência padrão é substituído usando o símbolo @ para definir uma expressão embutida.

A seguinte marcação carrega _ProductPartial.cshtml:

<partial name="_ProductPartial" for="Product">

A exibição parcial é associada à propriedade Product do modelo de página associado:

using Microsoft.AspNetCore.Mvc.RazorPages;
using TagHelpersBuiltIn.Models;

namespace TagHelpersBuiltIn.Pages
{
    public class ProductModel : PageModel
    {
        public Product Product { get; set; }

        public void OnGet()
        {
            Product = new Product
            {
                Number = 1,
                Name = "Test product",
                Description = "This is a test product"
            };
        }
    }
}

modelo

O atributo model atribui uma instância de modelo a ser passada para a exibição parcial. O atributo model não pode ser usado com o atributo for.

Na marcação a seguir, é criada uma nova instância do objeto Product que é passada ao atributo model para associação:

<partial name="_ProductPartial"
         model='new Product { Number = 1, Name = "Test product", Description = "This is a test" }'>

view-data

O atributo view-data atribui um ViewDataDictionary a ser passado para a exibição parcial. A seguinte marcação faz com que toda a coleção ViewData fique acessível para a exibição parcial:

@{
    ViewData["IsNumberReadOnly"] = true;
}

<partial name="_ProductViewDataPartial" for="Product" view-data="ViewData">

No código anterior, o valor da chave IsNumberReadOnly é definido como true e adicionado à coleção ViewData. Consequentemente, ViewData["IsNumberReadOnly"] se torna acessível dentro da exibição parcial a seguir:

@model TagHelpersBuiltIn.Models.Product

<div class="form-group">
    <label asp-for="Number"></label>
    @if ((bool)ViewData["IsNumberReadOnly"])
    {
        <input asp-for="Number" type="number" class="form-control" readonly />
    }
    else
    {
        <input asp-for="Number" type="number" class="form-control" />
    }
</div>
<div class="form-group">
    <label asp-for="Name"></label>
    <input asp-for="Name" type="text" class="form-control" />
</div>
<div class="form-group">
    <label asp-for="Description"></label>
    <textarea asp-for="Description" rows="4" cols="50" class="form-control"></textarea>
</div>

Neste exemplo, o valor de ViewData["IsNumberReadOnly"] determina se o campo Número é exibido como somente leitura.

Migrar de um auxiliar HTML

Considere o seguinte exemplo de auxiliar HTML assíncrono. Uma coleção de produtos é iterada e exibida. Segundo o primeiro parâmetro do método PartialAsync, a exibição parcial _ProductPartial.cshtml é carregada. Uma instância do modelo Product é passada para a exibição parcial para associação.

@foreach (var product in Model.Products)
{
    @await Html.PartialAsync("_ProductPartial", product)
}

O auxiliar de marca parcial seguir alcança o mesmo comportamento de renderização assíncrona que o auxiliar HTML PartialAsync. Uma instância de modelo Product é atribuída ao atributo model para associação à exibição parcial.

@foreach (var product in Model.Products)
{
    <partial name="_ProductPartial" model="@product" />
}