ASP.NET Core 中的部分檢視

發行項
11/30/2023

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

部分檢視是不含 @page 指示詞的 Razor 標記檔案 (.cshtml)，其在另一個標記檔案的轉譯輸出內轉譯 HTML 輸出。

部分檢視一詞在開發 MVC 應用程式時使用，其中標記檔案稱為檢視；或開發 Razor Pages 應用程式時使用，其中標記檔案稱為頁面。本主題一般將 MVC 檢視和 Razor Pages 頁面稱為標記檔案。

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

使用部分檢視的時機

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

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

在由多個邏輯部分組成的大型複雜標記檔案中，使用隔離至部分檢視中的每個部分具有優勢。標記檔案中的程式碼為可管理，因為標記僅包含整體頁面結構和對部分檢視的參考。
減少標記檔案中一般標記內容的重複。

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

部分檢視不應該用於維護一般版面配置項目。您應該在 _Layout.cshtml 檔案中指定一般版面配置項目。

請勿使用需要複雜轉譯邏輯或程式碼執行來轉譯標記的部分檢視。請使用檢視元件，而非部分檢視。

宣告部分檢視

部分檢視是在檢視資料夾 (MVC) 或 Pages 資料夾 (Razor Pages) 內維護之不含 @page 指示詞的 .cshtml 標記檔案。

在 ASP.NET Core MVC 中，控制器的 ViewResult 能夠傳回檢視或部分檢視。在 Razor Pages 中，PageModel 可能會傳回部分檢視，其以 PartialViewResult 物件表示。參考部分檢視一節介紹參考和轉譯部分檢視。

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

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

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

控制器的 ViewResult 能夠傳回檢視或部分檢視。參考部分檢視一節介紹參考和轉譯部分檢視。

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

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

參考部分檢視

在 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 協助程式

在標記檔案中，您可以使用兩種方法參考部分檢視：

非同步 HTML 協助程式
同步 HTML 協助程式

我們建議應用程式使用非同步 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 Analyzer 警告。例如，Partial 的存在會產生下列警告訊息：

使用 IHtmlHelper.Partial 可能會導致應用程式死結。請考慮使用<部分>標籤協助程式或 IHtmlHelper.PartialAsync。

將對 @Html.Partial 的呼叫取代為對 @await Html.PartialAsync 的呼叫或部分標籤協助程式。如需 Partial 標籤協助程式移轉的詳細資訊，請參閱從 HTML 協助程式移轉。

部分檢視探索

如果以不含檔案副檔名的名稱參考部分檢視，則會依所述順序搜尋下列位置：

Razor Pages

目前正在執行頁面的資料夾
頁面資料夾上方的目錄圖表
/Shared
/Pages/Shared
/Views/Shared

MVC

/Areas/<Area-Name>/Views/<Controller-Name>
/Areas/<Area-Name>/Views/Shared
/Views/Shared
/Pages/Shared

/Areas/<Area-Name>/Views/<Controller-Name>
/Areas/<Area-Name>/Views/Shared
/Views/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++;
    }
}

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

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

第二個部分檢視會轉譯文章的章節：

第一節索引：0

八十七年前...

第二節索引：1

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

第三節索引：2

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

ASP.NET Core 中的部分檢視

使用部分檢視的時機

宣告部分檢視

參考部分檢視

在 Razor Pages PageModel 中使用部分檢視

在標記檔案中使用部分檢視

部分標籤協助程式

非同步 HTML 協助程式

同步 HTML 協助程式

部分檢視探索

從部分檢視存取資料

其他資源

意見反應

其他資源