Vues partielles dans ASP.NET Core

Par Steve Smith, Maher JENDOUBI, Rick Anderson et Scott Sauber

Une vue partielle est un Razorfichier de balisage (.cshtml) sans une @pagedirective qui rend la sortie HTML à l’intérieur de la sortie rendue d’un autre fichier de balisage.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Quand utiliser des vues partielles ?

Les vues partielles sont utiles pour :

• Découper des fichiers de balisage volumineux en composants plus petits.

  Dans un grand fichier de balisage complexe composé de plusieurs parties logiques, il peut s’avérer utile de travailler sur chaque partie isolée dans une vue partielle. Le code dans le fichier de balisage est facile à gérer, puisqu’il contient uniquement la structure de page globale et les références aux vues partielles.

• Réduire la duplication du contenu de balisage commun entre les fichiers de balisage.

  Quand les mêmes éléments de balisage sont utilisés entre plusieurs fichiers de balisage, une vue partielle supprime la duplication du contenu de balisage dans un seul fichier de vue partielle. Quand le balisage est modifié dans la vue partielle, il met à jour la sortie rendue des fichiers de balisage qui utilisent cette vue partielle.

Les vues partielles ne doivent pas être utilisées pour tenir à jour des éléments de disposition communs. Ces éléments doivent être spécifiés dans des fichiers _Layout.cshtml.

N’utilisez pas une vue partielle quand du code ou une logique de rendu complexe doit être exécuté pour effectuer le rendu du balisage. Dans ce cas, utilisez un composant de vue à la place.

Déclarer des vues partielles

Référencer une vue partielle

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

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

Utiliser une vue partielle dans un fichier de balises

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

Assistance HTML asynchrone

Avec un Helper HTML, la bonne pratique est d’utiliser PartialAsync. PartialAsync retourne un type IHtmlContent wrappé dans un Task<TResult>. La méthode est référencée par l’ajout du préfixe @ à l’appel attendu :

@await Html.PartialAsync("_PartialName")

Si l’extension de fichier est spécifiée, la vue partielle référencée par le Helper HTML doit se trouver dans le même dossier que le fichier de balisage qui appelle la vue partielle :

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

L’exemple suivant référence une vue partielle à la racine de l’application. Les chemins qui commencent par un tilde et une barre oblique (~/) ou par une barre oblique seule (/) renvoient à la racine de l’application :

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

L’exemple suivant référence une vue partielle avec un chemin relatif :

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

Vous pouvez aussi effectuer le rendu d’une vue partielle avec RenderPartialAsync. Cette méthode ne retourne aucun IHtmlContent. Elle envoie la sortie rendue directement à la réponse. Comme elle ne retourne aucun résultat, cette méthode doit être appelée dans un bloc de code Razor :

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

Dans la mesure où elle envoie directement le contenu rendu, la méthode RenderPartialAsync est plus efficace dans certains scénarios. Dans les scénarios nécessitant de hautes performances, effectuez un test d’évaluation de la page à l’aide de ces deux approches et choisissez celle qui génère une réponse plus rapidement.

Assistance HTML synchrone

Partial et RenderPartial sont les équivalents synchrones de PartialAsync et RenderPartialAsync, respectivement. Les équivalents synchrones ne sont pas recommandés en raison du risque d’interblocage dans certains scénarios. Les méthodes synchrones sont prévues d’être supprimées dans une version ultérieure.

Découverte des vues partielles

Quand une vue partielle est référencée par son nom sans extension de fichier, les emplacements suivants sont recherchés dans l’ordre indiqué :

Les conventions suivantes s’appliquent à la détection des vues partielles :

• Vous pouvez avoir plusieurs vues partielles avec le même nom de fichier à condition que les vues partielles se trouvent dans des dossiers distincts.
• Quand vous référencez une vue partielle par son nom (sans extension de fichier) et que la vue partielle est présente à la fois dans le dossier de l’appelant et le dossier Partagé, la vue partielle fournie est celle du dossier de l’appelant. Si la vue partielle n’est pas présente dans le dossier de l’appelant, la vue partielle fournie est celle du dossier Partagé. Les vues partielles dans le dossier Partagé sont appelées vues partielles partagées ou vues partielles par défaut.
• Les vues partielles peuvent être chaînées_, c’est-à-dire qu’une vue partielle peut appeler une autre vue partielle si une référence circulaire n’est pas formée par les appels. Les chemins relatifs sont toujours relatifs au fichier actuel, et non au fichier racine ou parent associé.

Accéder à des données à partir de vues partielles

Quand une vue partielle est instanciée, elle reçoit une copie du dictionnaire ViewData du parent. Les mises à jour apportées aux données de la vue partielle ne sont pas conservées dans la vue parente. Tout changement apporté à ViewData dans une vue partielle est perdu quand la vue partielle est retournée.

L’exemple suivant montre comment passer une instance de ViewDataDictionary à une vue partielle :

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

Vous pouvez passer un modèle dans une vue partielle. Le modèle peut être un objet personnalisé. Vous pouvez passer un modèle avec PartialAsync (envoie le rendu d’un bloc de contenu à l’appelant) ou avec RenderPartialAsync (transmet le contenu à la sortie) :

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

Dans l’exemple d’application, le balisage suivant montre la vue Views/Articles/Read.cshtml. La vue contient deux vues partielles. La seconde vue partielle passe un modèle et ViewData à la vue partielle. La surcharge de constructeur ViewDataDictionary passe un nouveau dictionnaire ViewData tout en conservant le dictionnaire ViewData existant.

@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 est la première vue partielle référencée par le Read.cshtmlfichier de balisage :

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

Views/Articles/_ArticleSection.cshtml est la deuxième vue partielle référencée par le Read.cshtmlfichier de balisage :

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Au moment de l’exécution, le rendu des vues partielles est effectué dans la sortie rendue du fichier de balisage parent, qui est elle-même rendue dans le fichier partagé _Layout.cshtml. La première vue partielle affiche le nom de l’auteur et la date de publication de l’article :

Abraham Lincoln

This partial view from <shared partial view file path>. 11/19/1863 12:00:00 AM

La seconde vue partielle affiche les sections de l’article :

Section One Index: 0

Four score and seven years ago ...

Section Two Index: 1

Now we are engaged in a great civil war, testing ...

Section Three Index: 2

But, in a larger sense, we can not dedicate ...

Ressources supplémentaires