Widoki częściowe na platformie ASP.NET Core

Przez Steve Smith, Maher JENDOUBI, Rick Anderson i Scott Sauber

Widok częściowy to Razor plik znaczników (.cshtml) bez @page dyrektywy, renderujący dane wyjściowe HTML w renderowanych danych wyjściowych innego pliku znaczników.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Kiedy używać widoków częściowych

Skuteczny sposób na wykorzystanie widoków częściowych to:

• Podziel duże pliki znaczników na mniejsze składniki.

  W dużym, złożonym pliku znaczników składającym się z kilku elementów logicznych istnieje zaleta pracy z każdym elementem odizolowanym do widoku częściowego. Kod w pliku znaczników można zarządzać, ponieważ znacznik zawiera tylko ogólną strukturę strony i odwołania do widoków częściowych.

• Zmniejsz duplikację wspólnej zawartości znaczników w plikach znaczników.

  Gdy te same elementy znaczników są używane w różnych plikach, widok częściowy pozwala na zredukowanie duplikacji treści znaczników, umieszczając ją w jednym wspólnym pliku widoku częściowego. Gdy znaczniki są zmieniane w widoku częściowym, aktualizuje renderowane dane wyjściowe plików znaczników korzystających z widoku częściowego.

Widoki częściowe nie powinny być używane do utrzymywania typowych elementów układu. Wspólne elementy układu należy określić w plikach _Layout.cshtml .

Nie używaj widoku częściowego tam, gdzie do renderowania wymagana jest złożona logika lub wykonywanie kodu. Zamiast widoku częściowego użyj składnika widoku.

Zadeklaruj widoki częściowe

Odwołanie do częściowego widoku

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

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

Używanie widoku częściowego w pliku znaczników

<partial name="_PartialName" />

<partial name="_PartialName.cshtml" />

<partial name="~/Pages/Folder/_PartialName.cshtml" />
<partial name="/Pages/Folder/_PartialName.cshtml" />

<partial name="~/Views/Folder/_PartialName.cshtml" />
<partial name="/Views/Folder/_PartialName.cshtml" />

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

Asynchroniczny pomocnik HTML

W przypadku korzystania z pomocnika HTML najlepszym rozwiązaniem jest użycie metody PartialAsync. Typ IHtmlContent zwracany przez PartialAsync jest opakowany w Task<TResult>. Metoda jest przywoływana przez poprzedzanie oczekiwanego wywołania znakiem @ :

@await Html.PartialAsync("_PartialName")

Gdy rozszerzenie pliku jest obecne, Pomocnik HTML odwołuje się do widoku częściowego, który musi znajdować się w tym samym folderze co plik znaczników wywołujący widok częściowy:

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

Poniższy przykład odwołuje się do widoku częściowego z katalogu głównego aplikacji. Ścieżki rozpoczynające się od tyldy z ukośnikiem (~/) lub samego ukośnika (/) odwołują się do katalogu głównego aplikacji:

@await Html.PartialAsync("~/Pages/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Pages/Folder/_PartialName.cshtml")

@await Html.PartialAsync("~/Views/Folder/_PartialName.cshtml")
@await Html.PartialAsync("/Views/Folder/_PartialName.cshtml")

Poniższy przykład odwołuje się do widoku częściowego ze ścieżką względną:

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

Alternatywnie można renderować widok częściowy za pomocą polecenia RenderPartialAsync. Ta metoda nie zwraca elementu IHtmlContent. Przesyła strumieniowo renderowane dane wyjściowe bezpośrednio do odpowiedzi. Ponieważ metoda nie zwraca wyniku, musi być wywoływana w Razor bloku kodu:

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

Ponieważ RenderPartialAsync strumień renderowanej zawartości zapewnia lepszą wydajność w niektórych scenariuszach. W sytuacjach krytycznych dla wydajności należy porównać stronę przy użyciu obu metod i użyć podejścia, które generuje szybszą odpowiedź.

Synchroniczny pomocnik HTML

Partial i RenderPartial są odpowiednio synchronicznymi odpowiednikami PartialAsync i RenderPartialAsync. Synchroniczne odpowiedniki nie są zalecane, ponieważ istnieją scenariusze, w których zakleszczają. Metody synchroniczne są przeznaczone do usunięcia w przyszłej wersji.

Odkrywanie częściowego widoku

Gdy widok częściowy jest przywoływany według nazwy bez rozszerzenia pliku, następujące lokalizacje przeszukuje się w podanej kolejności:

Następujące konwencje mają zastosowanie do odnajdywania widoku częściowego:

• Różne widoki częściowe o tej samej nazwie pliku są dozwolone, gdy widoki częściowe znajdują się w różnych folderach.
• W przypadku odwoływania się do widoku częściowego po nazwie, bez rozszerzenia pliku, i gdy widok częściowy jest obecny zarówno w folderze wywołującego, jak i w folderze Udostępnionym, widok częściowy z folderu wywołującego jest używany. Jeśli widok częściowy nie znajduje się w folderze obiektu wywołującego, widok częściowy jest udostępniany z folderu Udostępnione . Widoki częściowe w folderze Udostępnione są nazywane widokami częściowymi lub widokami domyślnymi.
• Widoki częściowe mogą być połączone — widok częściowy może wywołać inny widok częściowy, jeśli nie stworzy cyklicznego odwołania. Ścieżki względne odnoszą się zawsze do bieżącego pliku, a nie do katalogu głównego lub nadrzędnego pliku.

Uzyskiwanie dostępu do danych z widoków częściowych

W momencie tworzenia wystąpienia częściowego widoku, otrzymuje ono kopię słownika nadrzędnegoViewData. Aktualizacje wprowadzone w danych w widoku częściowym nie są utrwalane w widoku nadrzędnym. ViewData zmiany w widoku częściowym zostaną utracone, gdy widok częściowy powróci.

W poniższym przykładzie pokazano, jak przekazać wystąpienie ViewDataDictionary do widoku częściowego (partial view):

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

Model można przekazać do widoku częściowego. Model może być obiektem niestandardowym. Można przekazać model z PartialAsync (renderuje blok zawartości dla obiektu wywołującego) lub RenderPartialAsync (strumieniuje zawartość do wyjścia):

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

@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++;
    }
}

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

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Poniższy kod znaczników pokazuje widok Views/Articles/Read.cshtml w przykładowej aplikacji. Widok zawiera dwa widoki częściowe. Drugi widok częściowy przechodzi w modelu i ViewData do widoku częściowego. Przeciążenie konstruktora ViewDataDictionary służy do przekazywania nowego ViewData słownika przy zachowaniu istniejącego ViewData słownika.

@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 to pierwszy widok częściowy, do który odwołuje się Read.cshtml plik znaczników:

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

Views/Articles/_ArticleSection.cshtml to drugi widok częściowy, do który odwołuje się Read.cshtml plik znaczników:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Podczas wykonywania partiale są renderowane do wynikowych danych renderowania pliku znaczników nadrzędnych, które samo jest renderowane w ramach udostępnionego _Layout.cshtml. Pierwszy widok częściowy renderuje nazwę i datę publikacji autora artykułu:

Abraham Lincoln

Ten widok częściowy ze <ścieżki udostępnionego widoku częściowego>. 11/19/1863 12:00:00 AM

Drugi widok częściowy renderuje sekcje artykułu:

Indeks Sekcji Pierwszej: 0

Osiemdziesiąt siedem lat temu ...

Sekcja Druga, Indeks: 1

Teraz jesteśmy zaangażowani w wielką wojnę domową, która wystawia na próbę ...

Indeks sekcji trzy: 2

Ale, w szerszym sensie, nie możemy poświęcić ...

Dodatkowe zasoby