Částečná zobrazení v ASP.NET Core

Steve Smith, Maher JENDOUBI, Rick Anderson a Scott Sauber

Částečné zobrazení je Razor soubor revizí (.cshtml) bez @page direktivy, která vykresluje výstup HTML v rámci vykresleného výstupu jiného souboru revizí.

Termín částečné zobrazení se používá při vývoji aplikace MVC, kde se soubory revizí označují jako zobrazení, nebo Razor aplikace Pages, kde se soubory revizí nazývají stránky. Toto téma obecně odkazuje na zobrazení MVC a Razor stránky stránek jako soubory značek.

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Kdy použít částečná zobrazení

Částečná zobrazení představují efektivní způsob:

• Rozdělte velké soubory značek na menší komponenty.

  Ve velkém komplexním souboru s kódem složeným z několika logických částí je výhodné pracovat s každou částí izolovanou v částečném zobrazení. Kód v souboru revizí je spravovatelný, protože revize obsahuje pouze celkovou strukturu stránky a odkazy na částečná zobrazení.

• Snižte duplikaci běžného obsahu revizí napříč soubory revizí.

  Pokud se v souborech revizí používají stejné prvky značek, částečné zobrazení odebere duplikaci obsahu revizí do jednoho souboru s částečným zobrazením. Když se revize změní v částečném zobrazení, aktualizuje vykreslený výstup souborů revizí, které používají částečné zobrazení.

Částečná zobrazení by se neměla používat k údržbě běžných prvků rozložení. Běžné prvky rozložení by měly být zadány v souborech _Layout.cshtml .

Nepoužívejte částečné zobrazení, ve kterém je k vykreslení kódu potřeba složitá logika vykreslování nebo provádění kódu. Místo částečného zobrazení použijte součást zobrazení.

Deklarace částečných zobrazení

Částečné zobrazení je .cshtml soubor revizí bez @page direktivy udržované ve složce Views (MVC) nebo Pages (RazorPages).

V ASP.NET Core MVC může kontroler ViewResult vrátit zobrazení nebo částečné zobrazení. Na Razor stránkách PageModel může vrátit částečné zobrazení reprezentované jako PartialViewResult objekt. Odkazování a vykreslení částečných zobrazení je popsáno v části Odkazování na částečné zobrazení .

Na rozdíl od zobrazení nebo vykreslování stránky MVC se částečné zobrazení nespustí _ViewStart.cshtml. Další informace najdete _ViewStart.cshtmlv tématu Rozložení v ASP.NET Core.

Názvy souborů částečného zobrazení často začínají podtržítkem (_). Tato konvence vytváření názvů není nutná, ale pomáhá vizuálně odlišit částečná zobrazení od zobrazení a stránek.

Odkaz na částečné zobrazení

Použití částečného Razor zobrazení v modelu PageModel stránky

V ASP.NET Core 2.0 nebo 2.1 následující metoda obslužné rutiny vykreslí částečné zobrazení _AuthorPartialRP.cshtml na odpověď:

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

V ASP.NET Core 2.2 nebo novější může metoda obslužné rutiny alternativně volat metodu Partial pro vytvoření objektu PartialViewResult :

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

Použití částečného zobrazení v souboru revizí

V souboru s revizemi existuje několik způsobů, jak odkazovat na částečné zobrazení. Doporučujeme, aby aplikace používaly jeden z následujících přístupů asynchronního vykreslování:

• Pomocná rutina částečné značky
• Asynchronní pomocník HTML

Pomocná rutina částečné značky

Pomocník částečné značky vyžaduje ASP.NET Core 2.1 nebo novější.

Pomocník částečné značky vykresluje obsah asynchronně a používá syntaxi podobné html:

<partial name="_PartialName" />

Pokud je k dispozici přípona souboru, pomocník značky odkazuje na částečné zobrazení, které musí být ve stejné složce jako soubor značek, který volá částečné zobrazení:

<partial name="_PartialName.cshtml" />

Následující příklad odkazuje na částečné zobrazení z kořenového adresáře aplikace. Cesty, které začínají lomítkem (~/) nebo lomítkem (/) odkazují na kořen aplikace:

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" />

Následující příklad odkazuje na částečné zobrazení s relativní cestou:

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

Další informace najdete v tématu Částečné pomocné rutiny značek v ASP.NET Core.

Asynchronní pomocník HTML

Při použití pomocné rutiny HTML je osvědčeným postupem použít PartialAsync. PartialAsyncIHtmlContent vrátí typ zabalený v objektu Task<TResult>. Na metodu odkazuje předpona očekávaného volání znakem @ :

@await Html.PartialAsync("_PartialName")

Pokud je přípona souboru přítomna, pomocník HTML odkazuje na částečné zobrazení, které musí být ve stejné složce jako soubor značek volající částečné zobrazení:

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

Následující příklad odkazuje na částečné zobrazení z kořenového adresáře aplikace. Cesty, které začínají lomítkem (~/) nebo lomítkem (/) odkazují na kořen aplikace:

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")

Následující příklad odkazuje na částečné zobrazení s relativní cestou:

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

Alternativně můžete vykreslit částečné zobrazení pomocí RenderPartialAsyncfunkce . Tato metoda nevrací znak IHtmlContent. Streamuje vykreslený výstup přímo do odpovědi. Protože metoda nevrací výsledek, musí být volána v Razor rámci bloku kódu:

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

Vzhledem k tomu, že RenderPartialAsync streamy vykreslují obsah, poskytují v některých scénářích lepší výkon. V kritických situacích s výkonem proveďte srovnávací testy stránky pomocí obou přístupů a použijte přístup, který generuje rychlejší odpověď.

Synchronní pomocník HTML

Partiala RenderPartial jsou synchronní ekvivalenty a RenderPartialAsyncPartialAsync v uvedeném pořadí. Synchronní ekvivalenty se nedoporučují, protože existují scénáře, ve kterých dochází k vzájemnému zablokování. Synchronní metody jsou cílem odebrání v budoucí verzi.

Důležité

Pokud potřebujete spustit kód, použijte místo částečného zobrazení komponentu zobrazení.

Volání Partial nebo RenderPartial výsledky v upozornění analyzátoru sady Visual Studio Například přítomnost Partial přináší následující upozornění:

Použití IHtmlHelper.Partial může vést k zablokování aplikace. Zvažte použití <částečné> pomocné rutiny značek nebo IHtmlHelper.PartialAsync.

Nahraďte volání @Html.Partial @await Html.PartialAsync pomocí pomocné rutiny částečné značky. Další informace o částečné migraci pomocné rutiny značek naleznete v tématu Migrace z pomocníka HTML.

Částečné zjišťování zobrazení

Pokud je částečné zobrazení odkazováno podle názvu bez přípony souboru, prohledávají se ve stavovém pořadí následující umístění:

Razor Pages

1. Aktuálně se spouští složka stránky.
2. Adresářové grafy nad složkou stránky
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

Následující konvence platí pro částečné zjišťování zobrazení:

• Různá částečná zobrazení se stejným názvem souboru jsou povolená, pokud jsou částečná zobrazení v různých složkách.
• Při odkazování na částečné zobrazení podle názvu bez přípony souboru a částečné zobrazení se nachází ve složce volajícího i ve sdílené složce, částečné zobrazení ve složce volajícího poskytuje částečné zobrazení. Pokud částečné zobrazení není ve složce volajícího, zobrazí se částečné zobrazení ze sdílené složky. Částečná zobrazení ve sdílené složce se nazývají sdílená částečná zobrazení nebo výchozí částečná zobrazení.
• Částečná zobrazení můžou být zřetězený – částečné zobrazení může volat jiné částečné zobrazení, pokud volání nevytvoří cyklický odkaz. Relativní cesty jsou vždy relativní vzhledem k aktuálnímu souboru, nikoli ke kořenovému adresáři nebo nadřazenosti souboru.

Poznámka:

Definice Razor section v částečném zobrazení je pro nadřazené soubory revizí neviditelná. Je section viditelný pouze pro částečné zobrazení, ve kterém je definováno.

Přístup k datům z částečných zobrazení

Když se vytvoří instance částečného zobrazení, obdrží kopii slovníku nadřazeného objektu ViewData . Aktualizace dat v rámci částečného zobrazení se neuchovávají do nadřazeného zobrazení. ViewData změny v částečném zobrazení se ztratí, když se částečné zobrazení vrátí.

Následující příklad ukazuje, jak předat instanci ViewDataDictionary do částečného zobrazení:

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

Model můžete předat do částečného zobrazení. Model může být vlastní objekt. Model PartialAsync můžete předat (vykreslí blok obsahu volajícímu) nebo RenderPartialAsync (streamuje obsah do výstupu):

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

Razor Pages

Následující kód v ukázkové aplikaci je ze Pages/ArticlesRP/ReadRP.cshtml stránky. Stránka obsahuje dvě částečná zobrazení. Druhé částečné zobrazení předá v modelu a ViewData částečnému zobrazení. Přetížení konstruktoru ViewDataDictionary se používá k předání nového ViewData slovníku při zachování existujícího ViewData slovníku.

@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 je první částečné zobrazení, na které ReadRP.cshtml odkazuje soubor revizí:

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml je druhé částečné zobrazení, na které ReadRP.cshtml odkazuje soubor revizí:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC

Následující kód v ukázkové aplikaci ukazuje Views/Articles/Read.cshtml zobrazení. Zobrazení obsahuje dvě částečná zobrazení. Druhé částečné zobrazení předá v modelu a ViewData částečnému zobrazení. Přetížení konstruktoru ViewDataDictionary se používá k předání nového ViewData slovníku při zachování existujícího ViewData slovníku.

@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 je první částečné zobrazení, na které Read.cshtml odkazuje soubor revizí:

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

Views/Articles/_ArticleSection.cshtml je druhé částečné zobrazení, na které Read.cshtml odkazuje soubor revizí:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Za běhu se částečné hodnoty vykreslují do vykresleného výstupu nadřazeného souboru revizí, který se v rámci sdíleného _Layout.cshtmlsouboru vykreslí . První částečné zobrazení vykreslí jméno autora článku a datum publikování:

Abraham Lincoln

Toto částečné zobrazení ze <sdílené částečné cesty> k souboru zobrazení. 11.19.1863 12:00:00

Druhé částečné zobrazení vykreslí oddíly článku:

Index 1 oddílu: 0

Čtyři skóre a před sedmi lety ...

Index 2 oddílu: 1

Nyní jsme zapojeni do velké občanské války, testování ...

Index třetí části: 2

Ale ve větším smyslu nemůžeme vyhradit ...

Další materiály

• Referenční informace k syntaxi Razor pro ASP.NET Core
• Pomocné rutiny značek v ASP.NET Core
• Pomocná rutina částečné značky v jádru ASP.NET
• Zobrazení komponent v ASP.NET Core
• Oblasti v ASP.NET Core