Visualizações parciais no ASP.NET Core

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

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

O termo visualização parcial é usado ao desenvolver um aplicativo MVC, onde os arquivos de marcação são chamados de exibições, ou um aplicativo Pages, onde os Razor arquivos de marcação são chamados de páginas. Este tópico refere-se genericamente a exibições MVC e Razor páginas Pages como arquivos de marcação.

Visualizar ou descarregar amostra de código (como descarregar)

Quando usar modos de exibição parciais

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

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

  Em um arquivo de marcação grande e complexo composto por várias peças lógicas, há uma vantagem em trabalhar com cada peça isolada em uma visão parcial. O código no arquivo de marcação é gerenciável porque a marcação contém apenas a estrutura geral da página e referências a exibições parciais.

• Reduza 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 em arquivos de marcação, uma exibição parcial remove a duplicação do conteúdo da 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 devem ser usadas para manter elementos de layout comuns. Elementos de layout comuns devem ser especificados em arquivos _Layout.cshtml .

Não use uma exibição parcial onde 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 vista parcial, utilize um componente de vista.

Declarar vistas parciais

Uma exibição parcial é um arquivo de .cshtml marcação sem uma @page diretiva mantida na pasta Views (MVC) ou na pasta Pages (Razor Pages).

No MVC ASP.NET Core, um controlador ViewResult é capaz de retornar uma exibição ou uma exibição parcial. No Razor Pages, um PageModel pode retornar uma exibição parcial representada como um PartialViewResult objeto. A referência e a renderização de exibições parciais são descritas na seção Fazer referência a uma exibição parcial .

Ao contrário da vista MVC ou da renderização de página, uma vista parcial não é executada _ViewStart.cshtml. Para obter mais informações sobre _ViewStart.cshtml, consulte Layout no ASP.NET Core.

Os nomes de arquivo de exibição parcial geralmente começam com um sublinhado (_). Esta convenção de nomenclatura não é necessária, mas ajuda a diferenciar visualmente vistas parciais de vistas e páginas.

Fazer referência a uma vista parcial

Utilizar uma vista parcial num PageModel de Razor Pages

No ASP.NET Core 2.0 ou 2.1, o seguinte método manipulador renderiza a vista parcial _AuthorPartialRP.cshtml para a resposta.

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

No ASP.NET Core 2.2 ou posterior, um método manipulador pode, alternativamente, chamar o Partial método para produzir um PartialViewResult objeto:

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

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

Em um arquivo de marcação, há várias maneiras de fazer referência a uma exibição parcial. Recomendamos que os aplicativos usem uma das seguintes abordagens de renderização assíncrona:

• Auxiliar de tag parcial
• Auxiliar de HTML assíncrono

Auxiliar de etiqueta parcial

O Auxiliar de Tag Parcial requer ASP.NET Core 2.1 ou posterior.

O Auxiliar de Marca Parcial processa o conteúdo de forma assíncrona e usa uma sintaxe semelhante a HTML:

<partial name="_PartialName" />

Quando uma extensão de arquivo está presente, o Auxiliar de Tag faz referência a uma exibição parcial que deve estar na mesma pasta que o arquivo de marcação que chama a exibição parcial:

<partial name="_PartialName.cshtml" />

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

Razor Páginas

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

MVC

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

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

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

Para obter mais informações, consulte Auxiliar de tag parcial no ASP.NET Core.

Auxiliar de HTML assíncrono

Ao usar um HTML Helper, a prática recomendada é usar PartialAsync. PartialAsync retorna um tipo IHtmlContent encapsulado num Task<TResult>. O método é referenciado prefixando a chamada esperada com um @ caractere:

@await Html.PartialAsync("_PartialName")

Quando a extensão do ficheiro está presente, o HTML Helper faz referência a uma visualização parcial que deve estar na mesma pasta que o ficheiro de marcação que invoca a visualização parcial.

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

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

Razor Páginas

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

MVC

@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, você pode renderizar uma exibição parcial com RenderPartialAsync. Este método não retorna um IHtmlContent. Ele transmite a saída renderizada diretamente para a resposta. Como o método não retorna um resultado, ele deve ser chamado dentro de um bloco de Razor código:

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

Como RenderPartialAsync processa conteúdo renderizado, proporciona um melhor desempenho em alguns cenários. Em situações críticas de desempenho, avalie a página usando ambas as abordagens e use a abordagem que gera uma resposta mais rápida.

Auxiliar de HTML síncrono

Partial e RenderPartial são os equivalentes síncronos de PartialAsync e RenderPartialAsync, respetivamente. Os equivalentes síncronos não são recomendados porque há cenários em que eles entram em deadlock. Os métodos síncronos são destinados à remoção numa próxima versão.

Important

Se você precisar executar código, use um componente de exibição em vez de uma exibição parcial.

Chamando Partial ou RenderPartial resulta em um aviso do analisador do Visual Studio. Por exemplo, a presença de Partial gera a seguinte mensagem de aviso:

O uso de IHtmlHelper.Partial pode resultar em bloqueios de aplicativos. Considere utilizar o Tag Helper <partial> ou IHtmlHelper.PartialAsync.

Substitua chamadas para @Html.Partial por @await Html.PartialAsync ou o Auxiliar de Tag Parcial. Para obter mais informações sobre a migração do Auxiliar de Tag Parcial, consulte Migrar de um Auxiliar de HTML.

Descoberta de visualização parcial

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

Razor Páginas

1. Pasta da página em execução no momento
2. Gráfico de diretório acima da pasta da página
3. /Shared
4. /Pages/Shared
5. /Views/Shared

MVC

1. /Areas/<Area-Name>/Views/<Controller-Name>
2. /Areas/<Area-Name>/Views/Shared
3. /Views/Shared
4. /Pages/Shared

As seguintes convenções se aplicam à descoberta de visualização parcial:

• Diferentes modos de exibição parciais com o mesmo nome de arquivo são permitidos quando os modos de exibição parciais estão em pastas diferentes.
• Ao referenciar uma exibição parcial por nome, sem uma extensão de arquivo, e a exibição parcial está presente tanto na pasta do chamador como na pasta Shared, a exibição parcial fornecida é a que está na pasta do chamador. Se a vista parcial não estiver presente na pasta do chamador, a vista parcial é fornecida a partir da pasta Partilhada . Os modos de exibição parciais na pasta Compartilhado são chamados de modos de exibição parciais compartilhados ou modos de exibição parciais padrão.
• As visualizações parciais podem ser encadeadas — uma exibição parcial pode chamar outra exibição parcial se uma referência circular não for formada pelas chamadas. Os caminhos relativos são sempre relativos ao arquivo atual, não à raiz ou pai do arquivo.

Note

Um Razorsection definido numa vista parcial é invisível para os ficheiros de marcação pai. O section só é visível para a vista parcial em que está definido.

Aceder a dados a partir de vistas parciais

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

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

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

Você pode passar um modelo para uma visualizaçã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)

Razor Páginas

"O código a seguir no aplicativo de exemplo é da página Pages/ArticlesRP/ReadRP.cshtml." A página contém duas vistas parciais. A segunda vista parcial passa para um modelo e ViewData para a vista parcial. A sobrecarga do ViewDataDictionary construtor é utilizada para introduzir um novo dicionário ViewData, enquanto se mantém o dicionário existente ViewData.

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

Pages/Shared/_AuthorPartialRP.cshtml é a primeira visão parcial referenciada pelo ficheiro de marcação ReadRP.cshtml

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml é a segunda vista parcial referenciada pelo ficheiro de marcação ReadRP.cshtml.

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC

A marcação a seguir no aplicativo de exemplo mostra a Views/Articles/Read.cshtml exibição. A visualização contém duas visualizações parciais. A segunda vista parcial passa para um modelo e ViewData para a vista parcial. A sobrecarga do ViewDataDictionary construtor é utilizada para introduzir um novo dicionário ViewData, enquanto se mantém o dicionário existente ViewData.

@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 visão parcial referenciada pelo ficheiro 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 vista parcial referenciada pelo ficheiro de marcação Read.cshtml.

@using PartialViewsSample.ViewModels
@model ArticleSection

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

No tempo de execução, os fragmentos são renderizados na saída renderizada do ficheiro de marcação pai, que por sua vez é renderizada dentro do ficheiro de marcação partilhado _Layout.cshtml. A primeira visualização parcial apresenta o nome do autor do artigo e a data de publicação:

Abraham Lincoln

Esta é uma vista parcial a partir do ficheiro de vista parcial partilhada no caminho <>. 19/11/1863 00:00:00

A segunda vista parcial apresenta as secções do artigo:

Índice da Secção Um: 0

Há quatro e sete anos...

Secção Dois Índice: 1

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

Secção Três Índice: 2

Mas, num sentido mais amplo, não podemos dedicar...

Recursos adicionais

• Razor referência de sintaxe para ASP.NET Core
• Ajuda de Etiquetas no ASP.NET Core
• Auxiliar de tag parcial no ASP.NET Core
• Ver componentes no ASP.NET Core
• Áreas em ASP.NET Core