Частичные представления в ASP.NET Core

Авторы: Стив Смит (Steve Smith), Махер Джендуби (Maher JENDOUBI), Рик Андерсон (Rick Anderson) и Скотт Саубер (Scott Sauber)

Частичное Razor представление — это файл разметки (.cshtml) без @page директивы, которая отображает выходные данные HTML в отрисованном выходных данных другого файла разметки.

Просмотреть или скачать образец кода (описание загрузки)

Когда следует использовать частичные представления

Частичные представления позволяют эффективно выполнять следующие задачи:

• Разбить большие файлы разметки на мелкие компоненты.

  Если используется крупный и сложный файл разметки, состоящий из нескольких логических частей, будет удобнее работать с этими частями как с отдельными частичными представлениями. Код в файле разметки сократится до разумного размера и будет содержать только общую структуру страницы и ссылки на частичные представления.

• Сократить дублирование элементов разметки в разных файлах разметки.

  Если во многих файлах разметки используются одинаковые элементы, частичное представление переносит такое дублируемое содержимого в отдельный файл частичного представления. Так, когда частичное представление изменится, автоматически обновятся выводимые данные для всех файлов разметки, использующих это частичное представление.

Частичные представления не следует использовать для выделения стандартных элементов макета. Повторяющиеся элементы макета следует определять в файле _Layout.cshtml.

Не используйте частичное представление там, где требуется сложная логика визуализации или выполнение кода для визуализации разметки. В этой ситуации лучше применить компонент представления.

Объявление частичных представлений

Ссылка на частичное представление

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

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

Использование частичного представления в файле разметки

<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" />

Асинхронное вспомогательное приложение HTML

Если вы используете вспомогательное приложение HTML, мы рекомендуем использовать PartialAsync. PartialAsync возвращает тип IHtmlContent в оболочке Task<TResult>. Для указания метода имя ожидающего вызова дополняется префиксом @.

@await Html.PartialAsync("_PartialName")

Если присутствует расширение файла, вспомогательная функция HTML ссылается на частичное представление, которое необходимо разместить в той же папке, что и вызывающий его файл разметки:

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

В следующем примере есть ссылка на частичное представление из корня приложения. Пути, начинающиеся с тильды и косой черты (~/) или с косой черты (/), используют корневой каталог приложения:

@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")

В следующем примере есть ссылка на частичное представление с относительным путем.

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

Вы также можете выполнить преобразование для просмотра частичного представления с помощью RenderPartialAsync. Этот метод не возвращает IHtmlContent. Он передает выводимые данные непосредственно в ответ в потоковом режиме. Так как метод не возвращает результат, он должен вызываться в Razor блоке кода:

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

Так как RenderPartialAsync выполняет потоковую передачу отображаемого содержимого, его производительность в некоторых сценариях выше. В системах критической важности следует замерить время отображения страницы при использовании двух подходов и использовать тот из них, который создает ответ быстрее.

Синхронное вспомогательное приложение HTML

Partial и RenderPartial — это синхронные эквиваленты PartialAsync и RenderPartialAsync соответственно. Мы не рекомендуем использовать синхронные эквиваленты, так как в некоторых случаях они приводят к взаимоблокировке. Синхронные методы будут удалены в будущем выпуске.

Обнаружение частичного представления

Если ссылка на частичное представление указывает только имя файла, без расширения, просматриваются следующие расположения в указанном порядке:

К обнаружению частичного представления применяются следующие соглашения:

• допускается использовать разные частичные представления с одним именем файла, если они расположены в разных папках;
• если ссылка на частичное представление содержит имя файла без расширения, а частичные представления с таким именем одновременно присутствуют в папке вызывающего объекта и в папке Shared, используется частичное представление из папки вызывающего объекта. Если нужное частичное представление отсутствует в папке вызывающего объекта, используется частичное представление из папки Shared. Частичных представления в папке Shared именуются общие частичные представления или частичные представления по умолчанию.
• Частичные представления могут быть связаны. Частичное представление может вызывать другое частичное представление, если циклическая ссылка не формируется вызовами. Относительные пути всегда указываются относительно расположения текущего файла, но не корневого или родительского каталога.

Доступ к данным из частичных представлений

Когда создается экземпляр частичного представления, он получает копию словаря ViewData из родительского представления. Изменения, вносимые в данные в частичном представлении, не сохраняются в родительском представлении. Изменения объекта ViewData в частичном представлении утрачиваются при возврате этого представления.

В следующем примере показано, как передать экземпляр ViewDataDictionary в частичное представление:

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

В частичное представление можно передать модель. Модель может являться пользовательским объектом. Модель можно передать с помощью PartialAsync (передает блок содержимого вызывающему объекту) или RenderPartialAsync (выполняет потоковую передачу содержимого в выходные данные):

@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>

Следующая разметка в примере приложения показывает Views/Articles/Read.cshtml представление. Это представление содержит два частичных представления. Второе частичное представление передает модель и объект ViewData в первое частичное представление. Используйте перегрузку конструктора ViewDataDictionary, чтобы передать новый словарь ViewData и при этом сохранить существующий словарь 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 — первое частичное представление, на который ссылается файл разметки Read.cshtml :

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

Views/Articles/_ArticleSection.cshtml — это второе частичное представление, на который ссылается файл разметки Read.cshtml :

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Во время выполнения части отображаются в отрисованных выходных данных родительского файла разметки, который сам по себе отображается в общей _Layout.cshtmlпапке. Первое частичное представление отображает имя автора статьи и дату публикации:

Abraham Lincoln

Это частичное представление из <общего каталога файлов частичного представления>. 11/19/1863 12:00:00 AM

Второе частичное представление отображает разделы статьи:

Section One Index: 0

Four score and seven years ago...

Section Two Index: 1

Now we are engaged in a great civil war, testing...

Section Three Index: 2

But, in a larger sense, we can not dedicate...

Дополнительные ресурсы