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

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

Частичное представление — это Razor файл разметки (. cshtml) без @page директивы, которая отображает выходные данные HTML в виде выходных данных, отображаемых в другом файле разметки.A partial view is a Razor markup file (.cshtml) without an @page directive that renders HTML output within another markup file's rendered output.

Термин частичное представление используется при разработке приложения MVC, где файлы разметки называются представлениями, или в Razor приложении страниц, где файлы разметки называются страницами.The term partial view is used when developing either an MVC app, where markup files are called views, or a Razor Pages app, where markup files are called pages. В этом разделе обобщенно рассматриваются представления MVC и страницы Razor страниц в виде файлов разметки.This topic generically refers to MVC views and Razor Pages pages as markup files.

Просмотреть или скачать образец кода (как скачивать)View or download sample code (how to download)

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

Частичные представления позволяют эффективно выполнять следующие задачи:Partial views are an effective way to:

  • Разбить большие файлы разметки на мелкие компоненты.Break up large markup files into smaller components.

    Если используется крупный и сложный файл разметки, состоящий из нескольких логических частей, будет удобнее работать с этими частями как с отдельными частичными представлениями.In a large, complex markup file composed of several logical pieces, there's an advantage to working with each piece isolated into a partial view. Код в файле разметки сократится до разумного размера и будет содержать только общую структуру страницы и ссылки на частичные представления.The code in the markup file is manageable because the markup only contains the overall page structure and references to partial views.

  • Сократить дублирование элементов разметки в разных файлах разметки.Reduce the duplication of common markup content across markup files.

    Если во многих файлах разметки используются одинаковые элементы, частичное представление переносит такое дублируемое содержимого в отдельный файл частичного представления.When the same markup elements are used across markup files, a partial view removes the duplication of markup content into one partial view file. Так, когда частичное представление изменится, автоматически обновятся выводимые данные для всех файлов разметки, использующих это частичное представление.When the markup is changed in the partial view, it updates the rendered output of the markup files that use the partial view.

Частичные представления не следует использовать для выделения стандартных элементов макета.Partial views shouldn't be used to maintain common layout elements. Повторяющиеся элементы макета следует определять в файле _Layout.cshtml.Common layout elements should be specified in _Layout.cshtml files.

Не используйте частичное представление там, где требуется сложная логика визуализации или выполнение кода для визуализации разметки.Don't use a partial view where complex rendering logic or code execution is required to render the markup. В этой ситуации лучше применить компонент представления.Instead of a partial view, use a view component.

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

Частичное представление — это файл разметки . cshtml без @page директивы, поддерживаемой в папке views (MVC) или папке pages ( Razor страницы).A partial view is a .cshtml markup file without an @page directive maintained within the Views folder (MVC) or Pages folder (Razor Pages).

В модели ASP.NET Core MVC элемент контроллера ViewResult может возвращать представление или частичное представление.In ASP.NET Core MVC, a controller's ViewResult is capable of returning either a view or a partial view. На Razor страницах объект PageModel может возвращать частичное представление, представленное в виде PartialViewResult объекта.In Razor Pages, a PageModel can return a partial view represented as a PartialViewResult object. См. дополнительные сведения о создании ссылок на частичные представления и их отображении.Referencing and rendering partial views is described in the Reference a partial view section.

В отличие от представления MVC и отображения страниц, частичное представление не выполняет файл _ViewStart.cshtml.Unlike MVC view or page rendering, a partial view doesn't run _ViewStart.cshtml. Дополнительные сведения о файле _ViewStart.cshtml, см. здесь: Макет в ASP.NET Core.For more information on _ViewStart.cshtml, see Макет в ASP.NET Core.

Имена файлов частичного представления обычно начинаются с символа подчеркивания (_).Partial view file names often begin with an underscore (_). Это соглашение об именовании не является обязательным требованием, но помогает отличать частичные представления от обычных представлений и страниц.This naming convention isn't required, but it helps to visually differentiate partial views from views and pages.

Частичное представление — это файл разметки .cshtml, размещенный в папке Views.A partial view is a .cshtml markup file maintained within the Views folder.

Элемент контроллера ViewResult может возвращать представление или частичное представление.A controller's ViewResult is capable of returning either a view or a partial view. См. дополнительные сведения о создании ссылок на частичные представления и их отображении.Referencing and rendering partial views is described in the Reference a partial view section.

В отличие от представления MVC, частичное представление не выполняет файл _ViewStart.cshtml.Unlike MVC view rendering, a partial view doesn't run _ViewStart.cshtml. Дополнительные сведения о файле _ViewStart.cshtml, см. здесь: Макет в ASP.NET Core.For more information on _ViewStart.cshtml, see Макет в ASP.NET Core.

Имена файлов частичного представления обычно начинаются с символа подчеркивания (_).Partial view file names often begin with an underscore (_). Это соглашение об именовании не является обязательным требованием, но помогает отличать частичные представления от обычных представлений.This naming convention isn't required, but it helps to visually differentiate partial views from views.

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

Использование частичного представления на Razor страницах PageModelUse a partial view in a Razor Pages PageModel

В ASP.NET Core 2,0 или 2,1 следующий метод обработчика преобразует частичное представление * _ аусорпартиалрп. cshtml* в ответ:In ASP.NET Core 2.0 or 2.1, the following handler method renders the _AuthorPartialRP.cshtml partial view to the response:

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

В ASP.NET Core 2.2 или более поздней версии метод обработчика может вызвать метод Partial, чтобы выдать объект PartialViewResult:In ASP.NET Core 2.2 or later, a handler method can alternatively call the Partial method to produce a PartialViewResult object:

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

Использование частичного представления в файле разметкиUse a partial view in a markup file

В файле разметки частичное представление может указываться несколькими способами.Within a markup file, there are several ways to reference a partial view. Мы рекомендуем использовать в приложениях один из следующих методов асинхронного отображения:We recommend that apps use one of the following asynchronous rendering approaches:

В файле разметки частичное представление может указываться двумя способами.Within a markup file, there are two ways to reference a partial view:

Мы рекомендуем использовать в приложениях асинхронное вспомогательное приложение HTML.We recommend that apps use the Asynchronous HTML Helper.

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

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

Вспомогательная функция тега частичного представления синхронно отображает содержимое, используя близкий к HTML синтаксис:The Partial Tag Helper renders content asynchronously and uses an HTML-like syntax:

<partial name="_PartialName" />

Если присутствует расширение файла, вспомогательная функция тега ссылается на частичное представление, которое необходимо разместить в той же папке, что и вызывающий его файл разметки:When a file extension is present, the Tag Helper references a partial view that must be in the same folder as the markup file calling the partial view:

<partial name="_PartialName.cshtml" />

В следующем примере есть ссылка на частичное представление из корня приложения.The following example references a partial view from the app root. Пути, начинающиеся с тильды и косой черты (~/) или с косой черты (/), используют корневой каталог приложения:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Razor СмRazor Pages

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

MVCMVC

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

В следующем примере есть ссылка на частичное представление с относительным путем.The following example references a partial view with a relative path:

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

Для получения дополнительной информации см. Вспомогательная функция тега частичного представления в ASP.NET Core.For more information, see Вспомогательная функция тега частичного представления в ASP.NET Core.

Асинхронный вспомогательный метод HTMLAsynchronous HTML Helper

Если вы используете вспомогательное приложение HTML, мы рекомендуем использовать PartialAsync.When using an HTML Helper, the best practice is to use PartialAsync. PartialAsync возвращает тип IHtmlContent в оболочке Task<TResult>.PartialAsync returns an IHtmlContent type wrapped in a Task<TResult>. Для указания метода имя ожидающего вызова дополняется префиксом @.The method is referenced by prefixing the awaited call with an @ character:

@await Html.PartialAsync("_PartialName")

Если присутствует расширение файла, вспомогательная функция HTML ссылается на частичное представление, которое необходимо разместить в той же папке, что и вызывающий его файл разметки:When the file extension is present, the HTML Helper references a partial view that must be in the same folder as the markup file calling the partial view:

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

В следующем примере есть ссылка на частичное представление из корня приложения.The following example references a partial view from the app root. Пути, начинающиеся с тильды и косой черты (~/) или с косой черты (/), используют корневой каталог приложения:Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Razor СмRazor Pages

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

MVCMVC

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

В следующем примере есть ссылка на частичное представление с относительным путем.The following example references a partial view with a relative path:

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

Вы также можете выполнить преобразование для просмотра частичного представления с помощью RenderPartialAsync.Alternatively, you can render a partial view with RenderPartialAsync. Этот метод не возвращает IHtmlContent.This method doesn't return an IHtmlContent. Он передает выводимые данные непосредственно в ответ в потоковом режиме.It streams the rendered output directly to the response. Поскольку метод не возвращает результат, он должен быть вызван в Razor блоке кода:Because the method doesn't return a result, it must be called within a Razor code block:

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

Так как RenderPartialAsync выполняет потоковую передачу отображаемого содержимого, его производительность в некоторых сценариях выше.Since RenderPartialAsync streams rendered content, it provides better performance in some scenarios. В системах критической важности следует замерить время отображения страницы при использовании двух подходов и использовать тот из них, который создает ответ быстрее.In performance-critical situations, benchmark the page using both approaches and use the approach that generates a faster response.

Синхронный вспомогательный метод HTMLSynchronous HTML Helper

Partial и RenderPartial — это синхронные эквиваленты PartialAsync и RenderPartialAsync соответственно.Partial and RenderPartial are the synchronous equivalents of PartialAsync and RenderPartialAsync, respectively. Мы не рекомендуем использовать синхронные эквиваленты, так как в некоторых случаях они приводят к взаимоблокировке.The synchronous equivalents aren't recommended because there are scenarios in which they deadlock. Синхронные методы будут удалены в будущем выпуске.The synchronous methods are targeted for removal in a future release.

Важно!

Если вам нужно выполнять код, используйте компонент представления вместо частичного представления.If you need to execute code, use a view component instead of a partial view.

Вызов Partial или RenderPartial генерирует предупреждение анализатора Visual Studio.Calling Partial or RenderPartial results in a Visual Studio analyzer warning. Например, наличие Partial приведет к появлению такого сообщения:For example, the presence of Partial yields the following warning message:

Использование IHtmlHelper.Partial может привести к взаимоблокировкам приложения.Use of IHtmlHelper.Partial may result in application deadlocks. Попробуйте использовать <частичное> вспомогательное приложение тега или IHtmlHelper.PartialAsync.Consider using <partial> Tag Helper or IHtmlHelper.PartialAsync.

Вместо вызовов @Html.Partial используйте @await Html.PartialAsync или вспомогательное приложение тега частичного представления.Replace calls to @Html.Partial with @await Html.PartialAsync or the Partial Tag Helper. Дополнительные сведения о переносе вспомогательной функции тега частичного представления см. в разделе Перенос из вспомогательного метода HTML.For more information on Partial Tag Helper migration, see Migrate from an HTML Helper.

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

Если ссылка на частичное представление указывает только имя файла, без расширения, просматриваются следующие расположения в указанном порядке:When a partial view is referenced by name without a file extension, the following locations are searched in the stated order:

Razor СмRazor Pages

  1. папка текущей выполняемой страницы;Currently executing page's folder
  2. граф каталога на уровень выше папки страницы.Directory graph above the page's folder
  3. /Shared
  4. /Pages/Shared
  5. /Views/Shared

MVCMVC

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

К обнаружению частичного представления применяются следующие соглашения:The following conventions apply to partial view discovery:

  • допускается использовать разные частичные представления с одним именем файла, если они расположены в разных папках;Different partial views with the same file name are allowed when the partial views are in different folders.
  • если ссылка на частичное представление содержит имя файла без расширения, а частичные представления с таким именем одновременно присутствуют в папке вызывающего объекта и в папке Shared, используется частичное представление из папки вызывающего объекта.When referencing a partial view by name without a file extension and the partial view is present in both the caller's folder and the Shared folder, the partial view in the caller's folder supplies the partial view. Если нужное частичное представление отсутствует в папке вызывающего объекта, используется частичное представление из папки Shared.If the partial view isn't present in the caller's folder, the partial view is provided from the Shared folder. Частичных представления в папке Shared именуются общие частичные представления или частичные представления по умолчанию.Partial views in the Shared folder are called shared partial views or default partial views.
  • Частичные представления могут быть объединены в цепочку — . частичное представление может вызывать другое частичное представление, если циклическая ссылка не сформирована вызовами.Partial views can be chained—a partial view can call another partial view if a circular reference isn't formed by the calls. Относительные пути всегда указываются относительно расположения текущего файла, но не корневого или родительского каталога.Relative paths are always relative to the current file, not to the root or parent of the file.

Примечание

Объект, Razor section определенный в частичном представлении, невидим для родительских файлов разметки.A Razor section defined in a partial view is invisible to parent markup files. Объект section видим только для частичного представления, в котором он определен.The section is only visible to the partial view in which it's defined.

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

Когда создается экземпляр частичного представления, он получает копию словаря ViewData из родительского представления.When a partial view is instantiated, it receives a copy of the parent's ViewData dictionary. Изменения, вносимые в данные в частичном представлении, не сохраняются в родительском представлении.Updates made to the data within the partial view aren't persisted to the parent view. Изменения объекта ViewData в частичном представлении утрачиваются при возврате этого представления.ViewData changes in a partial view are lost when the partial view returns.

В следующем примере показано, как передать экземпляр ViewDataDictionary в частичное представление:The following example demonstrates how to pass an instance of ViewDataDictionary to a partial view:

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

В частичное представление можно передать модель.You can pass a model into a partial view. Модель может являться пользовательским объектом.The model can be a custom object. Модель можно передать с помощью PartialAsync (передает блок содержимого вызывающему объекту) или RenderPartialAsync (выполняет потоковую передачу содержимого в выходные данные):You can pass a model with PartialAsync (renders a block of content to the caller) or RenderPartialAsync (streams the content to the output):

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

Razor СмRazor Pages

Следующая разметка для примера приложения взята со страницы Pages/ArticlesRP/ReadRP.cshtml.The following markup in the sample app is from the Pages/ArticlesRP/ReadRP.cshtml page. Эта страница содержит два частичных представления.The page contains two partial views. Второе частичное представление передает модель и объект ViewData в первое частичное представление.The second partial view passes in a model and ViewData to the partial view. Используйте перегрузку конструктора ViewDataDictionary, чтобы передать новый словарь ViewData и при этом сохранить существующий словарь ViewData.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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:Pages/Shared/_AuthorPartialRP.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml — это второе частичное представление, указанное в файле разметки ReadRP.cshtml:Pages/ArticlesRP/_ArticleSectionRP.cshtml is the second partial view referenced by the ReadRP.cshtml markup file:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVCMVC

В приведенной ниже разметке для примера приложения показано представление Views/Articles/Read.cshtml.The following markup in the sample app shows the Views/Articles/Read.cshtml view. Это представление содержит два частичных представления.The view contains two partial views. Второе частичное представление передает модель и объект ViewData в первое частичное представление.The second partial view passes in a model and ViewData to the partial view. Используйте перегрузку конструктора ViewDataDictionary, чтобы передать новый словарь ViewData и при этом сохранить существующий словарь ViewData.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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:Views/Shared/_AuthorPartial.cshtml is the first partial view referenced by the Read.cshtml markup file:

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

Views/Shared/_ArticleSection.cshtml — это второе частичное представление, указанное в файле разметки Read.cshtml:Views/Articles/_ArticleSection.cshtml is the second partial view referenced by the Read.cshtml markup file:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Во время выполнения частичные представления встраиваются в выходные данные родительского представления, которое также преобразовывается для просмотра в общем макете _Layout.cshtml.At runtime, the partials are rendered into the parent markup file's rendered output, which itself is rendered within the shared _Layout.cshtml. Первое частичное представление отображает имя автора статьи и дату публикации:The first partial view renders the article author's name and publication date:

Abraham LincolnAbraham Lincoln

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

Второе частичное представление отображает разделы статьи:The second partial view renders the article's sections:

Section One Index: 0Section One Index: 0

Four score and seven years ago...Four score and seven years ago ...

Section Two Index: 1Section Two Index: 1

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

Section Three Index: 2Section Three Index: 2

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

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