Vues partielles dans ASP.NET CorePartial views in ASP.NET Core

Par Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson et Scott SauberBy Steve Smith, Luke Latham, Maher JENDOUBI, Rick Anderson, and Scott Sauber

Une vue partielle est un fichier de balisage Razor (.cshtml) qui effectue le rendu d’une sortie HTML dans la sortie rendue d’un autre fichier de balisage.A partial view is a Razor markup file (.cshtml) that renders HTML output within another markup file's rendered output.

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 du développement d’une application Razor Pages, où les fichiers de balisage sont appelés pages.The term partial view is used when developing either an MVC app, where markup files are called views, or a Razor Pages app, where markup files are called pages. Cette rubrique désigne les vues MVC et les pages Razor Pages avec le terme générique fichiers de balisage.This topic generically refers to MVC views and Razor Pages pages as markup files.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Quand utiliser des vues partielles ?When to use partial views

Les vues partielles sont utiles pour :Partial views are an effective way to:

  • Découper des fichiers de balisage volumineux en composants plus petits.Break up large markup files into smaller components.

    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.In a large, complex markup file composed of several logical pieces, there's an advantage to working with each piece isolated into a partial view. 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.The code in the markup file is manageable because the markup only contains the overall page structure and references to partial views.

  • Réduire la duplication du contenu de balisage commun entre les fichiers de balisage.Reduce the duplication of common markup content across markup files.

    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.When the same markup elements are used across markup files, a partial view removes the duplication of markup content into one partial view file. Quand le balisage est modifié dans la vue partielle, il met à jour la sortie rendue des fichiers de balisage qui utilisent cette vue partielle.When the markup is changed in the partial view, it updates the rendered output of the markup files that use the partial view.

Les vues partielles ne doivent pas être utilisées pour tenir à jour des éléments de disposition communs.Partial views shouldn't be used to maintain common layout elements. Ces éléments doivent être spécifiés dans des fichiers _Layout.cshtml.Common layout elements should be specified in _Layout.cshtml files.

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.Don't use a partial view where complex rendering logic or code execution is required to render the markup. Dans ce cas, utilisez un composant de vue à la place.Instead of a partial view, use a view component.

Déclarer des vues partiellesDeclare partial views

Une vue partielle est un fichier de balisage .cshtml tenu à jour dans le dossier Vues (MVC) ou le dossier Pages (Razor Pages).A partial view is a .cshtml markup file maintained within the Views folder (MVC) or Pages folder (Razor Pages).

Dans ASP.NET Core MVC, le ViewResult d’un contrôleur peut retourner une vue ou une vue partielle.In ASP.NET Core MVC, a controller's ViewResult is capable of returning either a view or a partial view. Une fonctionnalité similaire est prévue pour Razor Pages dans ASP.NET Core 2.2.An analogous capability is planned for Razor Pages in ASP.NET Core 2.2. Dans Razor Pages, un PageModel peut retourner un PartialViewResult.In Razor Pages, a PageModel can return a PartialViewResult. Le référencement et le rendu des vues partielles sont décrits dans la section Référencer une vue partielle.Referencing and rendering partial views is described in the Reference a partial view section.

Contrairement au rendu d’une vue MVC ou d’une page, une vue partielle n’exécute pas _ViewStart.cshtml.Unlike MVC view or page rendering, a partial view doesn't run _ViewStart.cshtml. Pour plus d’informations sur _ViewStart.cshtml, consultez Disposition dans ASP.NET Core.For more information on _ViewStart.cshtml, see Disposition dans ASP.NET Core.

Les noms de fichiers des vues partielles commencent souvent par un trait de soulignement (_).Partial view file names often begin with an underscore (_). Cette convention de nommage n’est pas obligatoire, mais elle aide à différencier visuellement les vues partielles des autres vues et pages.This naming convention isn't required, but it helps to visually differentiate partial views from views and pages.

Une vue partielle est un fichier de balisage .cshtml tenu à jour dans le dossier Vues.A partial view is a .cshtml markup file maintained within the Views folder.

Le ViewResult d’un contrôleur peut retourner une vue ou une vue partielle.A controller's ViewResult is capable of returning either a view or a partial view.

Contrairement au rendu d’une vue MVC, une vue partielle n’exécute pas _ViewStart.cshtml.Unlike MVC view rendering, a partial view doesn't run _ViewStart.cshtml. Pour plus d’informations sur _ViewStart.cshtml, consultez Disposition dans ASP.NET Core.For more information on _ViewStart.cshtml, see Disposition dans ASP.NET Core.

Les noms de fichiers des vues partielles commencent souvent par un trait de soulignement (_).Partial view file names often begin with an underscore (_). Cette convention de nommage n’est pas obligatoire, mais elle aide à différencier visuellement les vues partielles des autres vues.This naming convention isn't required, but it helps to visually differentiate partial views from views.

Référencer une vue partielleReference a partial view

Il y a plusieurs façons de référencer une vue partielle au sein d’un fichier de balisage.Within a markup file, there are several ways to reference a partial view. Pour vos applications, nous vous recommandons de choisir l’une des approches de rendu asynchrone suivantes :We recommend that apps use one of the following asynchronous rendering approaches:

Il y a deux façons de référencer une vue partielle au sein d’un fichier de balisage :Within a markup file, there are two ways to reference a partial view:

Pour vos applications, nous vous recommandons d’utiliser le Helper HTML asynchrone.We recommend that apps use the Asynchronous HTML Helper.

Tag Helper PartialPartial Tag Helper

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

Le Tag Helper Partial effectue un rendu asynchrone et utilise une syntaxe de type HTML :The Partial Tag Helper renders content asynchronously and uses an HTML-like syntax:

<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 :When a file extension is present, the Tag Helper references a partial view that must be in the same folder as the markup file calling the partial view:

<partial name="_PartialName.cshtml" />

L’exemple suivant référence une vue partielle à la racine de l’application.The following example references a partial view from the app root. Les chemins qui commencent par un tilde et une barre oblique (~/) ou par une barre oblique seule (/) renvoient à la racine de l’application :Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Pages RazorRazor Pages

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

MVCMVC

<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 :The following example references a partial view with a relative path:

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

Pour plus d'informations, consultez Tag Helper Partial dans ASP.NET Core.For more information, see Tag Helper Partial dans ASP.NET Core.

Assistance HTML asynchroneAsynchronous HTML Helper

Avec un Helper HTML, la bonne pratique est d’utiliser PartialAsync.When using an HTML Helper, the best practice is to use PartialAsync. PartialAsync retourne un type IHtmlContent wrappé dans un Task<TResult>.PartialAsync returns an IHtmlContent type wrapped in a Task<TResult>. La méthode est référencée par l’ajout du préfixe @ à l’appel attendu :The method is referenced by prefixing the awaited call with an @ character:

@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 :When the file extension is present, the HTML Helper references a partial view that must be in the same folder as the markup file calling the partial view:

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

L’exemple suivant référence une vue partielle à la racine de l’application.The following example references a partial view from the app root. Les chemins qui commencent par un tilde et une barre oblique (~/) ou par une barre oblique seule (/) renvoient à la racine de l’application :Paths that start with a tilde-slash (~/) or a slash (/) refer to the app root:

Pages RazorRazor Pages

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

MVCMVC

@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 :The following example references a partial view with a relative path:

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

Vous pouvez aussi effectuer le rendu d’une vue partielle avec RenderPartialAsync.Alternatively, you can render a partial view with RenderPartialAsync. Cette méthode ne retourne aucun IHtmlContent.This method doesn't return an IHtmlContent. Elle envoie la sortie rendue directement à la réponse.It streams the rendered output directly to the response. Comme elle ne retourne aucun résultat, cette méthode doit être appelée dans un bloc de code Razor :Because the method doesn't return a result, it must be called within a Razor code block:

@{
    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.Since RenderPartialAsync streams rendered content, it provides better performance in some scenarios. 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.In performance-critical situations, benchmark the page using both approaches and use the approach that generates a faster response.

Assistance HTML synchroneSynchronous HTML Helper

Partial et RenderPartial sont les équivalents synchrones de PartialAsync et RenderPartialAsync, respectivement.Partial and RenderPartial are the synchronous equivalents of PartialAsync and RenderPartialAsync, respectively. Les équivalents synchrones ne sont pas recommandés en raison du risque d’interblocage dans certains scénarios.The synchronous equivalents aren't recommended because there are scenarios in which they deadlock. Les méthodes synchrones sont prévues d’être supprimées dans une version ultérieure.The synchronous methods are targeted for removal in a future release.

Important

Si vous devez exécuter du code, utilisez un composant de vue au lieu d’une vue partielle.If you need to execute code, use a view component instead of a partial view.

L’appel de Partial ou RenderPartial génère un avertissement de l’analyseur Visual Studio.Calling Partial or RenderPartial results in a Visual Studio analyzer warning. Par exemple, la présence de Partial génère le message d’avertissement suivant :For example, the presence of Partial yields the following warning message:

L’utilisation de IHtmlHelper.Partial peut entraîner des interblocages d’application.Use of IHtmlHelper.Partial may result in application deadlocks. Utilisez plutôt un Tag Helper <Partial> ou IHtmlHelper.PartialAsync.Consider using <partial> Tag Helper or IHtmlHelper.PartialAsync.

Remplacez les appels à @Html.Partial par @await Html.PartialAsync ou le Tag Helper Partial.Replace calls to @Html.Partial with @await Html.PartialAsync or the Partial Tag Helper. Pour plus d’informations sur la migration du Tag Helper Partial, consultez Migrer à partir d’une assistance HTML.For more information on Partial Tag Helper migration, see Migrate from an HTML Helper.

Découverte des vues partiellesPartial view discovery

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é :When a partial view is referenced by name without a file extension, the following locations are searched in the stated order:

Pages RazorRazor Pages

  1. Dossier de la page en cours d’exécutionCurrently executing page's folder
  2. Directory Graph au-dessus du dossier de la pageDirectory graph above the page's folder
  3. /Shared
  4. /Pages/Shared
  5. /Views/Shared

MVCMVC

  1. /Areas/<Area-Name>/Views/<Controller-Name>
  2. /Areas/<Area-Name>/Views/Shared
  3. /Views/Shared
  4. /Pages/Shared
  1. /Areas/<Area-Name>/Views/<Controller-Name>
  2. /Areas/<Area-Name>/Views/Shared
  3. /Views/Shared

Les conventions suivantes s’appliquent à la détection des vues partielles :The following conventions apply to partial view discovery:

  • Vous pouvez avoir plusieurs vues partielles avec le même nom de fichier à condition que les vues partielles se trouvent dans des dossiers distincts.Different partial views with the same file name are allowed when the partial views are in different folders.
  • 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.When referencing a partial view by name without a file extension and the partial view is present in both the caller's folder and the Shared folder, the partial view in the caller's folder supplies the partial view. Si la vue partielle n’est pas présente dans le dossier de l’appelant, la vue partielle fournie est celle du dossier Partagé.If the partial view isn't present in the caller's folder, the partial view is provided from the Shared folder. Les vues partielles dans le dossier Partagé sont appelées vues partielles partagées ou vues partielles par défaut.Partial views in the Shared folder are called shared partial views or default partial views.
  • 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.Partial views can be chained—a partial view can call another partial view if a circular reference isn't formed by the calls. Les chemins relatifs sont toujours relatifs au fichier actuel, et non au fichier racine ou parent associé.Relative paths are always relative to the current file, not to the root or parent of the file.

Note

Une section Razor définie dans une vue partielle n’est pas visible par les fichiers de balisage parents.A Razor section defined in a partial view is invisible to parent markup files. La section est visible uniquement par la vue partielle dans laquelle elle est définie.The section is only visible to the partial view in which it's defined.

Accéder à des données à partir de vues partiellesAccess data from partial views

Quand une vue partielle est instanciée, elle reçoit une copie du dictionnaire ViewData du parent.When a partial view is instantiated, it receives a copy of the parent's ViewData dictionary. Les mises à jour apportées aux données de la vue partielle ne sont pas conservées dans la vue parente.Updates made to the data within the partial view aren't persisted to the parent view. Tout changement apporté à ViewData dans une vue partielle est perdu quand la vue partielle est retournée.ViewData changes in a partial view are lost when the partial view returns.

L’exemple suivant montre comment passer une instance de ViewDataDictionary à une vue partielle :The following example demonstrates how to pass an instance of ViewDataDictionary to a partial view:

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

Vous pouvez passer un modèle dans une vue partielle.You can pass a model into a partial view. Le modèle peut être un objet personnalisé.The model can be a custom object. 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) :You can pass a model with PartialAsync (renders a block of content to the caller) or RenderPartialAsync (streams the content to the output):

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

Pages RazorRazor Pages

Le balisage suivant dans l’exemple d’application est extrait de la page Pages/ArticlesRP/ReadRP.cshtml.The following markup in the sample app is from the Pages/ArticlesRP/ReadRP.cshtml page. La page contient deux vues partielles.The page contains two partial views. La seconde vue partielle passe un modèle et ViewData à la vue partielle.The second partial view passes in a model and ViewData to the partial view. La surcharge de constructeur ViewDataDictionary passe un nouveau dictionnaire ViewData tout en conservant le dictionnaire ViewData existant.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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 fichier de balisage ReadRP.cshtml :Pages/Shared/_AuthorPartialRP.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:

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

Pages/ArticlesRP/_ArticleSectionRP.cshtml est la seconde vue partielle référencée par le fichier de balisage ReadRP.cshtml :Pages/ArticlesRP/_ArticleSectionRP.cshtml is the second partial view referenced by the ReadRP.cshtml markup file:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

MVCMVC

Le balisage suivant dans l’exemple d’application illustre la vue Views/Articles/Read.cshtml.The following markup in the sample app shows the Views/Articles/Read.cshtml view. La vue contient deux vues partielles.The view contains two partial views. La seconde vue partielle passe un modèle et ViewData à la vue partielle.The second partial view passes in a model and ViewData to the partial view. La surcharge de constructeur ViewDataDictionary passe un nouveau dictionnaire ViewData tout en conservant le dictionnaire ViewData existant.The ViewDataDictionary constructor overload is used to pass a new ViewData dictionary while retaining the existing ViewData dictionary.

@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 fichier de balisage ReadRP.cshtml :Views/Shared/_AuthorPartial.cshtml is the first partial view referenced by the ReadRP.cshtml markup file:

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

Views/Articles/_ArticleSection.cshtml est la seconde vue partielle référencée par le fichier de balisage Read.cshtml :Views/Articles/_ArticleSection.cshtml is the second partial view referenced by the Read.cshtml markup file:

@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 _Layout.cshtml partagé.At runtime, the partials are rendered into the parent markup file's rendered output, which itself is rendered within the shared _Layout.cshtml. La première vue partielle affiche le nom de l’auteur et la date de publication de l’article :The first partial view renders the article author's name and publication date:

Abraham LincolnAbraham Lincoln

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

La seconde vue partielle affiche les sections de l’article :The second partial view renders the article's sections:

Section One Index: 0Section One Index: 0

Four score and seven years ago ...Four score and seven years ago ...

Section Two Index: 1Section Two Index: 1

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

Section Three Index: 2Section Three Index: 2

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

Ressources supplémentairesAdditional resources