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.

Le terme vue partielle s’emploie dans le cadre du développement d’une application MVC, où les fichiers de balisage sont appelés vues, ou une application Razor Pages où les fichiers de balisage sont appelés pages. Cette rubrique désigne les vues MVC et les pages Razor Pages avec le terme générique fichiers 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

Une vue partielle est un .cshtmlfichier de balisage sans une directive @page tenu à jour dans le dossier Vues (MVC) ou le dossier Pages (Razor Pages).

Dans ASP.NET Core MVC, le ViewResult d’un contrôleur peut retourner une vue ou une vue partielle. Dans RazorPages, un PageModel peut retourner une vue partielle représentée en tant qu’objet PartialViewResult. Le référencement et le rendu des vues partielles sont décrits dans la section Référencer une vue partielle.

Contrairement au rendu d’une vue MVC ou d’une page, une vue partielle n’exécute pas _ViewStart.cshtml. Pour plus d’informations sur _ViewStart.cshtml, consultez Disposition dans ASP.NET Core.

Les noms de fichiers des vues partielles commencent souvent par un trait de soulignement (_). Cette convention de nommage n’est pas obligatoire, mais elle aide à différencier visuellement les vues partielles des autres vues et pages.

Référencer une vue partielle

Utiliser une vue partielle dans un RazorPageModel Pages

Avec ASP.NET Core 2.0 ou 2.1, la méthode de gestionnaire suivante affiche la vue partielle _AuthorPartialRP.cshtml à la réponse :

C#

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

Avec ASP.NET Core 2.2 ou version ultérieure, une méthode de gestionnaire peut également appeler la méthode Partial pour générer un objet PartialViewResult :

C#

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

Utiliser une vue partielle dans un fichier de balises

Il y a plusieurs façons de référencer une vue partielle au sein d’un fichier de balisage. Pour vos applications, nous vous recommandons de choisir l’une des approches de rendu asynchrone suivantes :

• Tag Helper Partial
• Assistance HTML asynchrone

Tag Helper Partial

Le Tag Helper Partial nécessite ASP.NET Core 2.1 ou version ultérieure.

Le Tag Helper Partial effectue un rendu asynchrone et utilise une syntaxe de type HTML :

CSHTML

<partial name="_PartialName" />

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

CSHTML

<partial name="_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 :

Razor Pages

CSHTML

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

MVC

CSHTML

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

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

CSHTML

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

Pour plus d’informations, consultez assistance des balises partielle dans ASP.NET Core.

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 :

CSHTML

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

CSHTML

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

Razor Pages

CSHTML

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

MVC

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 :

CSHTML

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

CSHTML

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

Important

Si vous devez exécuter du code, utilisez un composant de vue au lieu d’une vue partielle.

L’appel de Partial ou RenderPartial génère un avertissement de l’analyseur Visual Studio. Par exemple, la présence de Partial génère le message d’avertissement suivant :

L’utilisation de IHtmlHelper.Partial peut entraîner des interblocages d’application. Utilisez plutôt un Tag Helper <Partial> ou IHtmlHelper.PartialAsync.

Remplacez les appels à @Html.Partial par @await Html.PartialAsync ou le Tag Helper Partial. Pour plus d’informations sur la migration du Tag Helper Partial, consultez Migrer à partir d’une assistance HTML.

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é :

Razor Pages

1. Dossier de la page en cours d’exécution
2. Directory Graph au-dessus du dossier de la page
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

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é.

Notes

Une section Razor définie dans une vue partielle n’est pas visible par les fichiers de balisage parents. La section est visible uniquement par la vue partielle dans laquelle elle est définie.

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 :

CSHTML

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

CSHTML

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

Razor Pages

Le balisage suivant dans l’exemple d’application est extrait de la page Pages/ArticlesRP/ReadRP.cshtml. La page 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.

CSHTML

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

CSHTML

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml est la deuxième vue partielle référencée par le ReadRP.cshtmlfichier de balisage :

CSHTML

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVC

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.

CSHTML

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

CSHTML

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

CSHTML

@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

• Informations de référence sur la syntaxe Razor pour ASP.NET Core
• Tag Helpers dans ASP.NET Core
• Tag Helper Partial dans ASP.NET Core
• Composants de vue dans ASP.NET Core
• Zones dans ASP.NET Core