Gedeeltelijke weergaven in ASP.NET Core

Door Steve Smith, Maher JENDOUBI, Rick Anderson en Scott Sauber

Een gedeeltelijke weergave is een Razor opmaakbestand (.cshtml) zonder een @page instructie waarmee HTML-uitvoer wordt weergegeven in de weergegeven uitvoer van een ander opmaakbestand.

Voorbeeldcode bekijken of downloaden (hoe download je)

Wanneer gedeeltelijke weergaven gebruiken

Gedeeltelijke weergaven zijn een effectieve manier om:

• Grote opmaakbestanden opsplitsen in kleinere onderdelen.

  In een groot, complex opmaakbestand dat bestaat uit verschillende logische onderdelen, is het een voordeel om met elk stuk te werken dat is geïsoleerd in een gedeeltelijke weergave. De code in het opmaakbestand kan worden beheerd omdat de opmaak alleen de algehele paginastructuur en verwijzingen naar gedeeltelijke weergaven bevat.

• Verminder de duplicatie van algemene opmaakinhoud in opmaakbestanden.

  Wanneer dezelfde opmaakelementen worden gebruikt voor opmaakbestanden, verwijdert een gedeeltelijke weergave de duplicatie van opmaakinhoud in één gedeeltelijk weergavebestand. Wanneer de opmaak wordt gewijzigd in de gedeeltelijke weergave, wordt de weergegeven uitvoer bijgewerkt van de opmaakbestanden die gebruikmaken van de gedeeltelijke weergave.

Gedeeltelijke weergaven mogen niet worden gebruikt om algemene indelingselementen te behouden. Algemene indelingselementen moeten worden opgegeven in _Layout.cshtml-bestanden .

Gebruik geen gedeeltelijke weergave waarbij complexe renderinglogica of codeuitvoering is vereist om de markering weer te geven. Gebruik een weergaveonderdeel in plaats van een gedeeltelijke weergave.

Gedeeltelijke weergaven declareren

Verwijzen naar een gedeeltelijke weergave

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

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

Een gedeeltelijke weergave gebruiken in een opmaakbestand

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

Asynchrone HTML Helper

Wanneer u een HTML Helper gebruikt, kunt u het beste PartialAsync gebruiken. PartialAsync retourneert een IHtmlContent type dat is verpakt in een Task<TResult>. Naar de methode wordt verwezen door de verwachte aanroep vooraf te laten gaan door een @ teken.

@await Html.PartialAsync("_PartialName")

Wanneer de bestandsextensie aanwezig is, verwijst de HTML Helper naar een gedeeltelijke weergave die zich in dezelfde map moet bevinden als het opmaakbestand dat de gedeeltelijke weergave aanroept:

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

In het volgende voorbeeld wordt verwezen naar een gedeeltelijke weergave vanuit de app-root. Paden die beginnen met een tilde-slash (~/) of een slash (/) verwijzen naar de applicatieroot:

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

In het volgende voorbeeld wordt verwezen naar een gedeeltelijke weergave met een relatief pad:

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

U kunt ook een gedeeltelijke weergave weergeven met RenderPartialAsync. De methode retourneert geen IHtmlContent. De gegenereerde uitvoer wordt rechtstreeks naar het antwoord gestreamd. Omdat de methode geen resultaat retourneert, moet deze worden aangeroepen binnen een Razor codeblok:

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

Omdat RenderPartialAsync streams inhoud weergeven, biedt het betere prestaties in sommige scenario's. In prestatiekritieke situaties benchmarkt u de pagina met behulp van beide benaderingen en gebruikt u de benadering die een snellere reactie genereert.

Synchrone HTML-helper

Partial en RenderPartial zijn respectievelijk de synchrone equivalenten van PartialAsync en RenderPartialAsync, respectievelijk. De synchrone equivalenten worden niet aanbevolen omdat er scenario's zijn waarin ze een impasse vormen. De synchrone methoden zijn bedoeld voor verwijdering in een toekomstige release.

Detectie van gedeeltelijke weergave

Wanneer naar een gedeeltelijke weergave wordt verwezen op naam zonder bestandsextensie, worden de volgende locaties in de vermelde volgorde doorzocht:

De volgende conventies zijn van toepassing op gedeeltelijke weergavedetectie:

• Verschillende gedeeltelijke weergaven met dezelfde bestandsnaam zijn toegestaan wanneer de gedeeltelijke weergaven zich in verschillende mappen bevinden.
• Wanneer u verwijst naar een gedeeltelijke weergave op naam zonder bestandsextensie en de gedeeltelijke weergave aanwezig is in zowel de map van de beller als de gedeelde map, levert de gedeeltelijke weergave in de map van de beller de gedeeltelijke weergave. Als de gedeeltelijke weergave niet aanwezig is in de map van de beller, wordt de gedeeltelijke weergave opgegeven vanuit de gedeelde map. Gedeeltelijke weergaven in de gedeelde map worden gedeelde gedeeltelijke weergaven of standaard gedeeltelijke weergaven genoemd.
• Gedeeltelijke weergaven kunnen worden gekoppeld. Een gedeeltelijke weergave kan een andere gedeeltelijke weergave aanroepen als een kringreferentie niet wordt gevormd door de aanroepen. Relatieve paden zijn altijd relatief ten opzichte van het huidige bestand, niet ten opzichte van de rootmap of het bovenliggende bestand.

Toegang tot gegevens vanuit gedeeltelijke weergaven

Wanneer een gedeeltelijke weergave wordt geïnstantieerd, ontvangt deze een kopie van de woordenlijst van het bovenliggende ViewData item. Updates die zijn aangebracht in de gegevens in de gedeeltelijke weergave, worden niet bewaard in de bovenliggende weergave. ViewData wijzigingen in een gedeeltelijke weergave gaan verloren wanneer de gedeeltelijke weergave wordt geretourneerd.

Bij het volgende voorbeeld wordt getoond hoe u een instantie van ViewDataDictionary naar een partiële weergave kunt doorgeven.

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

U kunt een model doorgeven aan een deelweergave. Het model kan een aangepast object zijn. U kunt een model doorgeven met PartialAsync (geeft een inhoudsblok weer aan de aanroeper) of RenderPartialAsync (streamt de inhoud naar de uitvoer):

@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>

In de volgende markup in de voorbeeld-app ziet u de Views/Articles/Read.cshtml weergave. De weergave bevat twee gedeeltelijke weergaven. De tweede gedeeltelijke weergave ontvangt een model en ViewData als invoer voor de gedeeltelijke weergave. De ViewDataDictionary overbelasting van de constructor wordt gebruikt om een nieuwe ViewData woordenlijst door te geven terwijl de bestaande ViewData woordenlijst behouden blijft.

@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 is de eerste gedeeltelijke weergave waarnaar wordt verwezen door het Read.cshtml opmaakbestand:

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

Views/Articles/_ArticleSection.cshtml is de tweede gedeeltelijke weergave waarnaar wordt verwezen door het Read.cshtml opmaakbestand:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Tijdens runtime worden de partials gerenderd in de gerenderde uitvoer van het bovenliggende markupbestand, die zelf wordt gerenderd binnen de gedeelde _Layout.cshtml. In de eerste gedeeltelijke weergave worden de naam en publicatiedatum van de auteur van het artikel weergegeven:

Abraham Lincoln

Deze gedeeltelijke weergave van het bestandspad< van >de gedeelde gedeeltelijke weergave. 11-19-1863 12:00:00 uur

In de tweede gedeeltelijke weergave worden de secties van het artikel weergegeven:

Sectie één indexnummer: 0

Zevenentachtig jaar geleden ...

Sectie Twee Index: 1

Nu zijn we bezig met een grote burgeroorlog, testen ...

Sectie Drie Index: 2

Maar in bredere zin kunnen we niet wijden ...

Aanvullende bronnen