Exibições parciais no ASP.NET Core

Por Steve Smith, Maher JENDOUBI, Rick Anderson e Scott Sauber

Uma exibição parcial é um arquivo de marcação Razor (.cshtml) sem uma diretiva de @page que renderiza a saída HTML dentro da saída processada de outro arquivo de marcação.

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

Quando usar exibições parciais

Exibições parciais são uma maneira eficaz de:

• Dividir arquivos de marcação grandes em componentes menores.

  Aproveitar a vantagem de trabalhar com cada parte isolada em uma exibição parcial em um arquivo de marcação grande e complexo, composto por diversas partes lógicas. O código no arquivo de marcação é gerenciável porque a marcação contém somente a estrutura de página geral e as referências a exibições parciais.

• Reduzir a duplicação de conteúdo de marcação comum em arquivos de marcação.

  Quando os mesmos elementos de marcação são usados nos arquivos de marcação, uma exibição parcial remove a duplicação de conteúdo de marcação em um arquivo de exibição parcial. Quando a marcação é alterada na exibição parcial, ela atualiza a saída renderizada dos arquivos de marcação que usam a exibição parcial.

As exibições parciais não podem ser usadas para manter os elementos de layout comuns. Os elementos de layout comuns precisam ser especificados nos arquivos _Layout.cshtml.

Não use uma exibição parcial em que a lógica de renderização complexa ou a execução de código são necessárias para renderizar a marcação. Em vez de uma exibição parcial, use um componente de exibição.

Declarar exibições parciais

Referenciar uma exibição parcial

public IActionResult OnGetPartial() =>
    new PartialViewResult
    {
        ViewName = "_AuthorPartialRP",
        ViewData = ViewData,
    };

public IActionResult OnGetPartial() =>
    Partial("_AuthorPartialRP");

Usar uma exibição parcial em um arquivo de marcação

<partial name="_PartialName" />

<partial name="_PartialName.cshtml" />

<partial name="~/Pages/Folder/_PartialName.cshtml" />
<partial name="/Pages/Folder/_PartialName.cshtml" />

<partial name="~/Views/Folder/_PartialName.cshtml" />
<partial name="/Views/Folder/_PartialName.cshtml" />

<partial name="../Account/_PartialName.cshtml" />

Auxiliar HTML assíncrono

Ao usar um Auxiliar HTML, a melhor prática é usar PartialAsync. PartialAsync retorna um tipo IHtmlContent encapsulado em um Task<TResult>. O método é referenciado prefixando a chamada em espera com um caractere @:

@await Html.PartialAsync("_PartialName")

Quando houver a extensão de arquivo, o Auxiliar de HTML fará referência a uma exibição parcial que precisa estar na mesma pasta que o arquivo de marcação que chama a exibição parcial:

@await Html.PartialAsync("_PartialName.cshtml")

O exemplo a seguir faz referência a uma exibição parcial da raiz do aplicativo. Caminhos que começam com um til-barra (~/) ou uma barra (/) referem-se à raiz do aplicativo:

@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")

@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")

O exemplo a seguir faz referência a uma exibição parcial com um caminho relativo:

@await Html.PartialAsync("../Account/_LoginPartial.cshtml")

Como alternativa, é possível renderizar uma exibição parcial com RenderPartialAsync. Esse método não retorna um IHtmlContent. Ele transmite a saída renderizada diretamente para a resposta. Como não retorna nenhum resultado, o método precisa ser chamado dentro de um bloco de código Razor:

@{
    await Html.RenderPartialAsync("_AuthorPartial");
}

Como RenderPartialAsync transmite conteúdo renderizado, ele apresenta melhor desempenho em alguns cenários. Em situações cruciais para o desempenho, submeta a página a benchmark usando ambas as abordagens e use aquela que gera uma resposta mais rápida.

Auxiliar de HTML assíncrono

Partial e RenderPartial são os equivalentes síncronos de PartialAsync e RenderPartialAsync, respectivamente. Os equivalentes síncronos não são recomendados porque há cenários em que eles realizam deadlock. Os métodos síncronos estão programados para serem removidos em uma versão futura.

Descoberta de exibição parcial

Quando uma exibição parcial é referenciada pelo nome sem uma extensão de arquivo, os seguintes locais são pesquisados na ordem indicada:

As convenções a seguir se aplicam à descoberta de exibição parcial:

• Diferentes exibições parciais com o mesmo nome de arquivo são permitidos quando as exibições parciais estão em pastas diferentes.
• Ao referenciar uma exibição parcial pelo nome sem uma extensão de arquivo e a exibição parcial está presente na pasta do chamador e na pasta Compartilhada, a exibição parcial na pasta do chamador fornece a exibição parcial. Se a exibição parcial não existir na pasta do chamador, ela será fornecida pela pasta Compartilhada. Exibições parciais na pasta Compartilhada são chamadas de exibições parciais compartilhadas ou exibições parciais padrão.
• As exibições parciais podem ser encadeadas — uma exibição parcial pode chamar uma outra exibição parcial se uma referência circular não tiver sido formada pelas chamadas. Caminhos relativos sempre são relativos ao arquivo atual, não à raiz ou ao pai do arquivo.

Acessar dados de exibições parciais

Quando uma exibição parcial é instanciada, ela recebe uma cópia do dicionário ViewData do pai. As atualizações feitas nos dados dentro da exibição parcial não são persistidas na exibição pai. Alterações a ViewData em uma exibição parcial são perdidas quando a exibição parcial retorna.

O exemplo a seguir demonstra como transmitir uma instância de ViewDataDictionary para uma exibição parcial:

@await Html.PartialAsync("_PartialName", customViewData)

Você pode passar um modelo para uma exibição parcial. O modelo pode ser um objeto personalizado. Você pode passar um modelo com PartialAsync (renderiza um bloco de conteúdo para o chamador) ou RenderPartialAsync (transmite o conteúdo para a saída):

@await Html.PartialAsync("_PartialName", model)

@model ReadRPModel

<h2>@Model.Article.Title</h2>
@* Pass the author's name to Pages\Shared\_AuthorPartialRP.cshtml *@
@await Html.PartialAsync("../Shared/_AuthorPartialRP", Model.Article.AuthorName)
@Model.Article.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Pages\ArticlesRP\_ArticleSectionRP.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Article.Sections)
    {
        await Html.PartialAsync("_ArticleSectionRP", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                });

        index++;
    }
}

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Pages/Shared/_AuthorPartialRP.cshtml.
</div>

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

A marcação a seguir na amostra de aplicativo mostra a exibição Views/Articles/Read.cshtml. A exibição contém duas exibições parciais. A segunda exibição parcial passa um modelo e ViewData para a exibição parcial. A sobrecarga do construtor ViewDataDictionary é usada para passar um novo dicionário ViewData, retendo ainda o dicionário ViewData existente.

@model PartialViewsSample.ViewModels.Article

<h2>@Model.Title</h2>
@* Pass the author's name to Views\Shared\_AuthorPartial.cshtml *@
@await Html.PartialAsync("_AuthorPartial", Model.AuthorName)
@Model.PublicationDate

@* Loop over the Sections and pass in a section and additional ViewData to 
   the strongly typed Views\Articles\_ArticleSection.cshtml partial view. *@
@{
    var index = 0;

    foreach (var section in Model.Sections)
    {
        @(await Html.PartialAsync("_ArticleSection", 
                                section,
                                new ViewDataDictionary(ViewData)
                                {
                                    { "index", index }
                                }))

        index++;
    }
}

Views/Shared/_AuthorPartial.cshtml é a primeira exibição parcial mencionada pelo arquivo de marcação Read.cshtml:

@model string
<div>
    <h3>@Model</h3>
    This partial view from /Views/Shared/_AuthorPartial.cshtml.
</div>

Views/Articles/_ArticleSection.cshtml é a segunda exibição parcial mencionada pelo arquivo de marcação Read.cshtml:

@using PartialViewsSample.ViewModels
@model ArticleSection

<h3>@Model.Title Index: @ViewData["index"]</h3>
<div>
    @Model.Content
</div>

No runtime, as exibições parciais são renderizadas para a saída renderizada do arquivo de marcação pai que, por sua vez, é renderizado dentro do _Layout.cshtml compartilhado. A primeira exibição parcial renderiza a data de publicação e o nome do autor do artigo:

Abraham Lincoln

Esta exibição parcial do <caminho do arquivo de exibição parcial compartilhada>. 19/11/1863 12:00:00 AM

A segunda exibição parcial renderiza as seções do artigo:

Índice da seção um: 0

Pontuação de quatro e há sete anos...

Índice da seção dois: 1

Agora estamos envolvidos em uma grande guerra civil, testando...

Índice da seção três: 2

Mas, em um sentido mais amplo, não podemos dedicar...

Recursos adicionais