共用方式為


ASP.NET Core 中的部分檢視

作者:Steve SmithMaher JENDOUBIRick AndersonScott 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 協助程式

部分標籤協助程式

部分標籤協助程式需要使用 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 協助程式時,最佳做法是使用 PartialAsyncPartialAsync 會傳回包裝在 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 協助程式

PartialRenderPartial 分別是 PartialAsyncRenderPartialAsync 的同步對等方法。 不建議使用同步對等,原因是會出現這些方法發生死結的情況。 同步方法將於未來版本中移除。

重要

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

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

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

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

部分檢視探索適用於下列慣例:

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

注意

父標記檔案不會顯示在部分視圖中定義的 Razorsectionsection 只會顯示在具有其定義的部分檢視。

從部分檢視存取資料

將部分檢視具現化時,會收到父檢視 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.cshtmlReadRP.cshtml 標記檔案所參考的第一個部分檢視:

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

Pages/ArticlesRP/_ArticleSectionRP.cshtmlReadRP.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.cshtmlRead.cshtml 標記檔案所參考的第一個部分檢視:

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

Views/Articles/_ArticleSection.cshtmlRead.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

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

其他資源