ASP.NET Core 中的分部视图

作者：Steve Smith、Maher JENDOUBI、Rick Anderson 和 Scott Sauber

部分视图是没有 @page 指令的 Razor 标记文件（.cshtml），它在另一个标记文件内呈现的输出中呈现 HTML 输出。

在开发 MVC 应用（其中标记文件称为“视图”）或 Razor Pages 应用（其中标记文件称为“页”）时，均会使用术语“分部视图”。 本主题通常将 MVC 视图和 Razor Pages 页面称为“标记文件”。

查看或下载示例代码（如何下载）

何时使用分部视图

分部视图是执行下列操作的有效方式：

• 将大型标记文件分解为更小的组件。

  在由多个逻辑部分组成的大型复杂标记文件中，在分部视图中处理隔开的每个部分是有利的。 标记文件中的代码是可管理的，因为标记仅包含整体页面结构和对分部视图的引用。

• 减少跨标记文件中常见标记内容的重复。

  当在标记文件中使用相同的标记元素时，分部视图会将重复的标记内容移到一个分部视图文件中。 在分部视图中更改标记后，它会更新使用该分部视图的标记文件呈现的输出。

不应使用分部视图来维护常见布局元素。 常见布局元素应在 _Layout.cshtml 文件中指定。

请勿使用需要复杂呈现逻辑或代码执行来呈现标记的分部视图。 使用视图组件而不是分部视图。

声明分部视图

部分视图是不带 @page 指令的 .cshtml 标记文件，在“视图”文件夹 (MVC) 或“页面”文件夹（Razor 页面）中进行维护。

在 ASP.NET Core MVC 中，控制器的 ViewResult 能够返回视图或分部视图。 在 Razor Pages 中，PageModel 可以返回表示为 PartialViewResult 对象的分部视图。 引用分部视图部分介绍了引用和呈现分部视图。

与 MVC 视图或页面呈现不同，分部视图不会运行 _ViewStart.cshtml_ViewStart.cshtml。 有关 _ViewStart.cshtml 的详细信息，请参阅 ASP.NET Core 中的布局。

分部视图的文件名通常以下划线 (_) 开头。 虽然未强制要求遵从此命名约定，但它有助于直观地将分部视图与视图和页面区分开来。

引用分部视图

在 Razor Pages 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 Pages

<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 返回包含在 Task<TResult> 中的 IHtmlContent 类型。 通过在等待的调用前添加 @ 字符前缀来引用该方法：

@await Html.PartialAsync("_PartialName")

当存在文件扩展名时，HTML 帮助程序会引用分部视图，该视图必须与调用分部视图的标记文件位于同一文件夹中：

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

以下示例从应用程序根目录引用分部视图。 以波形符斜杠 (~/) 或斜杠 (/) 开头的路径指代应用程序根目录：

Razor Pages

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

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

以下约定适用于分部视图发现：

• 当分部视图位于不同的文件夹中时，允许使用具有相同文件名的不同分部视图。
• 当按名称（无文件扩展名）引用分部视图且分部视图出现在调用方的文件夹和 文件夹中时，调用方文件夹中的分部视图会提供分部视图。 如果调用方文件夹中不存在分部视图，则会从 文件夹中提供分部视图。 文件夹中的分部视图称为“共享分部视图”或“默认分部视图”。
• 可以链接分部视图 - 如果调用没有形成循环引用，则分部视图可以调用另一个分部视图。 相对路径始终相对于当前文件，而不是相对于文件的根视图或父视图。

注意

分部视图中定义的 Razorsection 对父标记文件不可见。 section 仅对定义它时所在的分部视图可见。

通过分部视图访问数据

实例化分部视图时，它会获得父视图的 ViewData 字典的副本。 在分部视图内对数据所做的更新不会保存到父视图中。 在分部视图中的 ViewData 更改会在分部视图返回时丢失。

以下示例演示如何将 ViewDataDictionary的实例传递给分部视图：

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

还可将模型传入分部视图。 模型可以是自定义对象。 你可以使用 PartialAsync（向调用方呈现内容块）或 RenderPartialAsync（将内容流式传输到输出）传递模型：

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

Razor Pages

示例应用程序中的以下标记来自 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++;
    }
}

Views/Shared/_AuthorPartial.cshtml 是 Read.cshtml 标记文件引用的第一个分部视图Pages/Shared/_AuthorPartialRP.cshtmlReadRP.cshtml：

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

Pages/ArticlesRP/_ArticleSectionRP.cshtmlPages/ArticlesRP/_ArticleSectionRP.cshtml 是ReadRP.cshtml ReadRP.cshtml 标记文件引用的第二个分部视图：

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC

示例应用中的以下标记显示 Views/Articles/Read.cshtmlViews/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 标记文件引用的第一个分部视图Views/Shared/_AuthorPartial.cshtmlRead.cshtml：

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

Views/Articles/_ArticleSection.cshtmlViews/Articles/_ArticleSection.cshtml 是Read.cshtml Read.cshtml 标记文件引用的第二个分部视图：

@using PartialViewsSample.ViewModels
@model ArticleSection

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

在运行时，分部视图在父标记文件呈现的输出中呈现，而父标记文件本身在共享的 _Layout.cshtml 内呈现_Layout.cshtml。 第一个分部视图呈现文章作者的姓名和发布日期：

Abraham Lincoln

来自 <共享分部视图文件路径> 的分部视图。 1863 年 11 月 19 日中午 12:00:00

第二个分部视图呈现文章的各部分：

第一节索引：0

八十七年前...

第二节索引：1

如今，我们正在进行一场伟大的内战，考验着......

第三节索引：2

然而，从更广泛的意义上说，我们无法奉献...

其他资源

• ASP.NET Core 的 Razor 语法参考
• ASP.NET Core 中的标记帮助程序
• ASP.NET Core 中的部分标记帮助程序
• ASP.NET Core 中的视图组件
• ASP.NET Core 中的区域