ASP.NET Core 中的部分檢視

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

不含 Razor 指令的 .cshtml 標記檔案 (@page) 是一個部分檢視,其在另一個標記檔案的呈現輸出內呈現 HTML 輸出。

部分檢視一詞在開發 MVC 應用程式時使用,其中標記檔案稱為檢視;或開發 Razor Pages 應用程式時使用,其中標記檔案稱為頁面。 本文一般將 MVC 檢視與 Razor 頁面頁面稱為 標記檔案。

檢視或下載範例程式碼 \(英文\) (如何下載)

使用部分檢視的時機

針對下列項目,部分檢視是有效的方法:

  • 將大型標記檔案分解為較小的元件。

    在由多個邏輯部分組成的大型複雜標記檔案中,逐一獨立處理每個部分以便於部分檢視,這樣做有其優勢。 標記檔案中的程式碼為可管理,因為標記僅包含整體頁面結構和對部分檢視的參考。

  • 減少標記檔案中一般標記內容的重複。

    當在標記檔案中使用相同的標記項目時,部分檢視會將重複的標記內容移除至某個部分檢視檔案中。 在部分檢視中變更標記時,會更新使用部分檢視之標記檔案的轉譯輸出。

不應使用部分檢視來維持常見的版面配置元素。 您應該在 _Layout.cshtml 檔案中指定一般版面配置項目。

請勿在需要複雜呈現邏輯或程式碼執行的情況下使用部分視圖來轉譯標記。 請使用檢視元件,而非部分檢視。

宣告局部檢視

部分檢視是在.cshtml標記檔案中,沒有@page指示詞,維護在Views資料夾 (MVC) 或Pages資料夾 (Razor Pages) 中。

在 ASP.NET Core MVC 中,控制器的 ViewResult 能夠傳回檢視或部分檢視。 在 Razor Pages 中,PageModel 可以傳回一個由 PartialViewResult 物件表示的部分視圖。 參考部分檢視一節介紹如何參考和呈現部分檢視。

不同於 MVC 檢視或頁面轉譯,部分檢視不會執行 _ViewStart.cshtml。 如需 _ViewStart.cshtml 的詳細資訊,請參閱 ASP.NET Core 中的版面。

部分檢視檔案名稱通常以底線 (_) 開頭。 您不一定要依照這項慣例命名,但最好先在視覺呈現上將部分檢視與檢視和頁面區別開來。

部分檢視是在檢視.cshtml資料夾中維護的 標記檔案。

控制器的 ViewResult 能夠傳回檢視或部分檢視。 參考部分檢視一節介紹如何參考和呈現部分檢視。

不同於 MVC 檢視渲染,部分檢視不會執行 _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 頁面

<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 的同步對等方法。 不建議使用同步等效,因為在某些情況下可能會發生死結。 同步方法預計將於未來版本中移除。

Important

如果您需要執行程式碼,請使用檢視元件,而非部分檢視。

呼叫 Partial 或 RenderPartial 會產生 Visual Studio Analyzer 警告。 例如,Partial 的存在會產生下列警告訊息:

使用 IHtmlHelper.Partial 可能會導致應用程式死結。 請考慮使用<Partial Tag Helper>或 IHtmlHelper.PartialAsync。

將對 @Html.Partial 的呼叫取代為對 @await Html.PartialAsync 的呼叫或部分標籤協助程式。 如需 Partial 標籤協助器移轉的詳細資訊,請參閱從 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
  1. /Areas/<Area-Name>/Views/<Controller-Name>
  2. /Areas/<Area-Name>/Views/Shared
  3. /Views/Shared

下列慣例適用於部分檢視的發現:

  • 當部分檢視位於不同的資料夾中時,可允許使用具有相同檔案名稱的不同部分檢視。
  • 當以不含檔案副檔名的名稱參考部分檢視,且部分檢視出現在呼叫者的資料夾和共用資料夾中時,呼叫者資料夾中的部分檢視會提供部分檢視。 如果呼叫者資料夾中不存在部分檢視,則會從「共用」資料夾中提供部分檢視。 「共用」資料夾中的部分檢視稱為「共用部分檢視」或「預設部分檢視」。
  • 可鏈結部分檢視—如果呼叫未形成循環參考,則部分檢視可以呼叫另一個部分檢視。 相對路徑一律相對於目前的檔案,而不是相對於檔案的根目錄或父檔案。

Note

部分視圖中定義的 Razorsection 在父標記檔案中是不可見的。 section 僅在其定義的部分檢視中可見。

從局部視圖存取資料

當部分檢視實例化時,會收到父檢視字典的副本。 部分檢視內的資料更新不會被保存至父檢視。 傳回部分檢視時,部分檢視內的 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 中轉譯。 第一個部分視圖會呈現文章作者的名字和發行日期:

亞伯拉罕·林肯

此部分檢視來自<共用部分檢視的檔案路徑>。 1863 年 11 月 19 日上午 12:00:00

第二個部分視圖呈現文章的章節:

第一節索引:0

八十七年前...

第二節索引:1

如今,我們正在進行一場偉大的內戰,考驗著...

第三節索引:2

然而,從更廣泛的意義上說,我們無法在此奉獻...