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

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

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

Термин частичного представления используется при разработке приложения MVC, где файлы разметки называются представлениями или Razor приложением Pages, где файлы разметки называются страницами. Этот раздел обычно относится к представлениям MVC и Razor страницам Pages в качестве файлов разметки.

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

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

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

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

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

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

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

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

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

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

Частичное .cshtml представление — это файл разметки без директивы, поддерживаемой @page в папке Views (MVC) или в папке Pages (RazorPages).

В модели ASP.NET Core MVC элемент контроллера ViewResult может возвращать представление или частичное представление. В Razor Pages PageModel можно вернуть частичное представление, представленное PartialViewResult как объект. См. дополнительные сведения о создании ссылок на частичные представления и их отображении.

В отличие от представления MVC или отрисовки страниц, частичное представление не выполняется _ViewStart.cshtml. Дополнительные сведения см _ViewStart.cshtml. в разделе "Макет" в ASP.NET Core.

Имена файлов частичного представления обычно начинаются с символа подчеркивания (_). Это соглашение об именовании не является обязательным требованием, но помогает отличать частичные представления от обычных представлений и страниц.

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

Использование частичного Razor представления в PageModel

В ASP.NET Core 2.0 или 2.1 следующий метод обработчика отображает частичное представление _AuthorPartialRP.cshtml в ответ:

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

В ASP.NET Core 2.2 или более поздней версии метод обработчика может вызвать метод Partial, чтобы выдать объект PartialViewResult:

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

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

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

• Вспомогательная функция тега частичного представления
• Асинхронное вспомогательное приложение HTML

Вспомогательная функция тега частичного представления

Для вспомогательной функции тега частичного представления требуется ASP.NET Core 2.1 или более поздней версии.

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

<partial name="_PartialName" />

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

<partial name="_PartialName.cshtml" />

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

страницы Razor;

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

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

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

Дополнительные сведения см . в справке по частичному тегу в ASP.NET Core.

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

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

@await Html.PartialAsync("_PartialName")

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

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

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

страницы Razor;

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

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

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

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

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

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

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

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

Внимание

Если вам нужно выполнять код, используйте компонент представления вместо частичного представления.

Вызов Partial или RenderPartial генерирует предупреждение анализатора Visual Studio. Например, наличие Partial приведет к появлению такого сообщения:

Использование IHtmlHelper.Partial может привести к взаимоблокировкам приложения. Попробуйте использовать <частичное> вспомогательное приложение тега или IHtmlHelper.PartialAsync.

Вместо вызовов @Html.Partial используйте @await Html.PartialAsync или вспомогательное приложение тега частичного представления. Дополнительные сведения о переносе вспомогательной функции тега частичного представления см. в разделе Перенос из вспомогательного метода HTML.

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

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

страницы Razor;

1. папка текущей выполняемой страницы;
2. граф каталога на уровень выше папки страницы.
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

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

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

Примечание.

Определенное Razor section в частичном представлении невидимо для родительских файлов разметки. Объект section видим только для частичного представления, в котором он определен.

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

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

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

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

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

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

страницы Razor;

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

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml — это второе частичное представление, на который ссылается файл разметки ReadRP.cshtml :

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC;

Следующая разметка в примере приложения показывает 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...

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

• Справочник по синтаксису Razor для ASP.NET Core
• Вспомогательные функции тегов в ASP.NET Core
• Вспомогательный компонент частичного тега в ASP.NET Core
• Просмотр компонентов в ASP.NET Core
• Области в ASP.NET Core