Частичные представления в 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папке. Первое частичное представление отображает имя автора статьи и дату публикации:

Авраам Линкольн

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

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

Раздел один Индекс: 0

Четыре с половиной и семь лет назад...

Раздел второй, индекс: 1

Сейчас мы ведем великую гражданскую войну, проверяя...

Индекс раздела Три: 2

Но, в более широком смысле, мы не можем посвятить...

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