Dispositions ASP.NET Core Blazor

Cet article explique comment créer des composants de disposition réutilisables pour les applications Blazor.

Utilité des dispositions Blazor

Certains éléments d’application, comme les menus, les messages de copyright et les logos d’entreprise, font généralement partie de la présentation globale de l’application. Placer une copie du balisage de ces éléments dans tous les composants d’une application n’est pas efficace. Chaque fois qu’un de ces éléments est mis à jour, chaque composant qui utilise l’élément doit être mis à jour. Cette approche est coûteuse à gérer et peut entraîner un contenu incohérent si une mise à jour est manquée. Les dispositions résolvent ces problèmes.

Une disposition Blazor est un composant Razor qui partage le balisage avec les composants qui le référencent. Les dispositions peuvent utiliser la liaison de données, l’injection de dépendances et d’autres fonctionnalités des composants.

Composants de la disposition

Créer un composant de disposition

Pour créer un composant de disposition :

• Créez un composant Razor défini par un modèle Razor ou du code C#. Les composants de disposition basés sur un modèle Razor utilisent l’extension de fichier .razor, comme les composants Razor ordinaires. Étant donné que les composants de disposition sont partagés entre les composants d’une application, ils sont généralement placés dans le dossier Shared ou Layout de l’application. Toutefois, les dispositions peuvent être placées à n’importe quel emplacement accessible aux composants qui les utilisent. Par exemple, une disposition peut être placée dans le même dossier que les composants qui l’utilisent.
• Héritez du composant de LayoutComponentBase. LayoutComponentBase définit une propriété Body (type RenderFragment) pour le contenu rendu à l’intérieur de la disposition.
• Utilisez la syntaxe Razor@Body pour spécifier l’emplacement dans le balisage de disposition où le contenu est rendu.

Remarque

Pour plus d’informations sur RenderFragment, consultez Composants ASP.NET Core Razor.

Le composant DoctorWhoLayout suivant montre le modèle Razor d’un composant de disposition. La disposition hérite de LayoutComponentBase et définit @Body entre la barre de navigation (<nav>...</nav>) et le pied de page (<footer>...</footer>).

DoctorWhoLayout.razor:

@inherits LayoutComponentBase

<PageTitle>Doctor Who® Database</PageTitle>

<header>
    <h1>Doctor Who® Database</h1>
</header>

<nav>
    <a href="main-list">Main Episode List</a>
    <a href="search">Search</a>
    <a href="new">Add Episode</a>
</nav>

@Body

<footer>
    @TrademarkMessage
</footer>

@code {
    public string TrademarkMessage { get; set; } =
        "Doctor Who is a registered trademark of the BBC. " +
        "https://www.doctorwho.tv/ https://www.bbc.com";
}

MainLayout (composant)

Dans une application créée à partir d’un modèle de projet Blazor, le composant MainLayout est la disposition par défaut de l’application. La disposition de Blazor adopte Flexbox layout model (MDN documentation) (spécification W3C).

La fonctionnalité d’isolation CSS de Blazor applique des styles CSS isolés au composant MainLayout. Par convention, les styles sont fournis par la feuille de style associée du même nom, MainLayout.razor.css. L’implémentation du framework ASP.NET Core de la feuille de style est disponible pour inspection dans la source de référence ASP.NET Core (dépôt GitHub dotnet/aspnetcore) :

• Application web BlazorMainLayout.razor.css
• Blazor WebAssembly MainLayout.razor.css

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Appliquer une disposition

Rendre l’espace de noms de disposition disponible

Emplacements et espaces de noms des fichiers de disposition modifiés au fil du temps pour l’infrastructure Blazor. Selon la version de Blazor et le type de l’application Blazor que vous générez, il est possible que vous deviez indiquer l’espace de noms de la disposition lorsque vous l’utilisez. Lorsque vous référencez une implémentation de disposition et que la disposition est introuvable sans indiquer l’espace de noms de la disposition, suivez l’une des approches suivantes :

• Ajoutez une directive @using au fichier _Imports.razor pour l’emplacement des dispositions. Dans l’exemple suivant, un dossier de dispositions portant le nom Layout se trouve à l’intérieur d’un dossier Components et l’espace de noms de l’application est BlazorSample:

  @using BlazorSample.Components.Layout
  

• Ajoutez une directive @using en haut de la définition du composant où la disposition est utilisée :

  @using BlazorSample.Components.Layout
  @layout DoctorWhoLayout
  

• Qualifiez entièrement l’espace de noms de la disposition où elle est utilisée :

  @layout BlazorSample.Components.Layout.DoctorWhoLayout
  

Appliquer une disposition à un composant

Utilisez la directive @layoutRazor pour appliquer une disposition à un composant Razor routable qui a une directive @page. Le compilateur convertit @layout en LayoutAttribute et applique l’attribut à la classe de composant.

Le contenu du composant Episodes suivant est inséré dans DoctorWhoLayout à la position de @Body.

Episodes.razor:

@page "/episodes"
@layout DoctorWhoLayout

<h2>Doctor Who® Episodes</h2>

<ul>
    <li>
        <a href="https://www.bbc.co.uk/programmes/p00vfknq">
            <em>The Ribos Operation</em>
        </a>
    </li>
    <li>
        <a href="https://www.bbc.co.uk/programmes/p00vfdsb">
            <em>The Sunmakers</em>
        </a>
    </li>
    <li>
        <a href="https://www.bbc.co.uk/programmes/p00vhc26">
            <em>Nightmare of Eden</em>
        </a>
    </li>
</ul>

Le balisage HTML rendu suivant est produit par les composants DoctorWhoLayout et Episodes précédents. Le balisage superflu n’apparaît pas pour vous permettre de vous concentrer sur le contenu fourni par les deux composants impliqués :

• L’en-tête « base de données » H1 (<h1>...</h1>) dans l’en-tête (<header>...</header>), la barre de navigation (<nav>...</nav>) et les informations de marque déposée contenues dans le pied de page (<footer>...</footer>) proviennent du composant DoctorWhoLayout.
• L’en-tête « épisodes » H2 (<h2>...</h2>) et la liste d’épisodes (<ul>...</ul>) proviennent du composant Episodes.

<header>
    <h1 ...>...</h1>
</header>

<nav>
    ...
</nav>

<h2>...</h2>

<ul>
    <li>...</li>
    <li>...</li>
    <li>...</li>
</ul>

<footer>
    ...
</footer>

La spécification de la disposition directement dans un composant remplace une disposition par défaut :

• Définie par une directive @layout importée à partir d’un fichier _Imports.razor, comme décrit dans la section suivante Appliquer une disposition à un dossier de composants.
• Définie comme disposition par défaut de l’application, comme décrit dans la section Appliquer une disposition par défaut à une application plus loin dans cet article.

Appliquer une disposition à un dossier de composants

Chaque dossier d’une application peut éventuellement contenir un fichier de modèle nommé _Imports.razor. Le compilateur inclut les directives spécifiées dans le fichier d’importation dans tous les modèles Razor dans le même dossier et de manière récursive dans tous ses sous-dossiers. Par conséquent, un fichier _Imports.razor contenant @layout DoctorWhoLayout garantit que tous les composants d’un dossier utilisent le composant DoctorWhoLayout. Il n’est pas nécessaire d’ajouter à plusieurs reprises @layout DoctorWhoLayout à tous les composants Razor (.razor) dans le dossier et les sous-dossiers.

_Imports.razor:

@layout DoctorWhoLayout
...

Le fichier _Imports.razor est similaire au fichier _ViewImports.cshtml pour les vues et pages Razor, mais appliqué spécifiquement aux fichiers de composants Razor.

La spécification d’une disposition dans _Imports.razor remplace une disposition spécifiée comme disposition d’application par défaut du routeur, qui est décrite dans la section suivante.

Avertissement

N’ajoutez pas de directive Razor@layout au fichier racine _Imports.razor, ce qui entraîne une boucle infinie de dispositions. Pour contrôler la disposition d’application par défaut, spécifiez la disposition dans le composant Router. Pour plus d’informations, consultez la section suivante, Appliquer une disposition par défaut à une application.

Remarque

La directive @layoutRazor applique uniquement une disposition aux composants Razor routables avec une directive @page.

Appliquer une disposition par défaut à une application

Spécifiez la disposition d’application par défaut dans le composant RouteView du composant Router. Utilisez le paramètre DefaultLayout pour définir le type de disposition :

<RouteView RouteData="routeData" DefaultLayout="typeof({LAYOUT})" />

Dans l’exemple précédent, l’espace réservé {LAYOUT} est la disposition (par exemple, DoctorWhoLayout si le nom de fichier de la disposition est DoctorWhoLayout.razor). Il est possible que vous deviez identifier l’espace de noms de la disposition en fonction de la version .NET et du type d’application Blazor. Pour obtenir plus d’informations, consultez la section Rendre l’espace de noms de disposition disponible.

La spécification de la disposition en tant que disposition par défaut dans le Router du composant RouteView est une pratique utile, car vous pouvez remplacer la disposition par composant ou par dossier, comme décrit dans les sections précédentes de cet article. Nous vous recommandons d’utiliser le composant Router pour définir la disposition par défaut de l’application, car il s’agit de l’approche la plus générale et flexible pour l’utilisation de dispositions.

Appliquer une disposition à un contenu arbitraire (composant LayoutView)

Pour définir une disposition pour un contenu de modèle Razor arbitraire, spécifiez la disposition avec un composant LayoutView. Vous pouvez utiliser LayoutView dans n’importe quel composant Razor. L’exemple suivant définit un composant de disposition nommé ErrorLayout pour le modèle de NotFound du composant MainLayout (<NotFound>...</NotFound>).

<Router ...>
    <Found ...>
        ...
    </Found>
    <NotFound>
        <LayoutView Layout="typeof(ErrorLayout)">
            <h1>Page not found</h1>
            <p>Sorry, there's nothing at this address.</p>
        </LayoutView>
    </NotFound>
</Router>

Il est possible que vous deviez identifier l’espace de noms de la disposition en fonction de la version .NET et du type d’application Blazor. Pour obtenir plus d’informations, consultez la section Rendre l’espace de noms de disposition disponible.

Important

Les applications web Blazor n’utilisent pas le paramètre NotFound (<NotFound>...</NotFound>), mais le paramètre est pris en charge pour la compatibilité descendante afin d’éviter un changement cassant dans l’infrastructure. Le pipeline intergiciel ASP.NET Core côté serveur traite les requêtes sur le serveur. Utilisez des techniques côté serveur pour traiter les requêtes incorrectes. Pour plus d’informations, consultez Modes de rendu ASP.NET Core Blazor.

Dispositions imbriquées

Un composant peut référencer une disposition qui à son tour fait référence à une autre disposition. Par exemple, les dispositions imbriquées sont utilisées pour créer des structures de menu à plusieurs niveaux.

L’exemple suivant montre comment utiliser des dispositions imbriquées. Le composant Episodes indiqué dans la section Appliquer une disposition à un composant est le composant à afficher. Le composant fait référence au composant DoctorWhoLayout.

Le composant DoctorWhoLayout suivant est une version modifiée de l’exemple présenté plus haut dans cet article. Les éléments d’en-tête et de pied de page sont supprimés, et la disposition fait référence à une autre disposition, ProductionsLayout. Le composant Episodes est rendu où @Body apparaît dans DoctorWhoLayout.

DoctorWhoLayout.razor:

@inherits LayoutComponentBase
@layout ProductionsLayout

<PageTitle>Doctor Who® Database</PageTitle>

<h1>Doctor Who® Database</h1>

<nav>
    <a href="main-episode-list">Main Episode List</a>
    <a href="episode-search">Search</a>
    <a href="new-episode">Add Episode</a>
</nav>

@Body

<div>
    @TrademarkMessage
</div>

@code {
    public string TrademarkMessage { get; set; } =
        "Doctor Who is a registered trademark of the BBC. " +
        "https://www.doctorwho.tv/ https://www.bbc.com";
}

Le composant ProductionsLayout contient les éléments de disposition de niveau supérieur, où résident désormais les éléments d’en-tête (<header>...</header>) et de pied de page (<footer>...</footer>). La disposition DoctorWhoLayout avec le composant Episodes est rendue où @Body apparaît.

ProductionsLayout.razor:

@inherits LayoutComponentBase

<header>
    <h1>Productions</h1>
</header>

<nav>
    <a href="main-production-list">Main Production List</a>
    <a href="production-search">Search</a>
    <a href="new-production">Add Production</a>
</nav>

@Body

<footer>
    Footer of Productions Layout
</footer>

Le balisage HTML rendu suivant est généré par la disposition imbriquée précédente. Le balisage superflu n’apparaît pas pour vous permettre de vous concentrer sur le contenu imbriqué fourni par les trois composants impliqués :

• L’en-tête (<header>...</header>), la barre de navigation de production (<nav>...</nav>) et les éléments de pied de page (<footer>...</footer>) et leur contenu proviennent du composant ProductionsLayout.
• L’en-tête « base de données » H1 (<h1>...</h1>), la barre de navigation d’épisode (<nav>...</nav>) et les informations de marque déposée (<div>...</div>) proviennent du composant DoctorWhoLayout.
• L’en-tête « épisodes » H2 (<h2>...</h2>) et la liste d’épisodes (<ul>...</ul>) proviennent du composant Episodes.

<header>
    ...
</header>

<nav>
    <a href="main-production-list">Main Production List</a>
    <a href="production-search">Search</a>
    <a href="new-production">Add Production</a>
</nav>

<h1>...</h1>

<nav>
    <a href="main-episode-list">Main Episode List</a>
    <a href="episode-search">Search</a>
    <a href="new-episode">Add Episode</a>
</nav>

<h2>...</h2>

<ul>
    <li>...</li>
    <li>...</li>
    <li>...</li>
</ul>

<div>
    ...
</div>

<footer>
    ...
</footer>

Partager une disposition Razor Pages avec des composants intégrés

Lorsque les composants routables sont intégrés à une application Razor Pages, la disposition partagée de l’application peut être utilisée avec les composants. Pour plus d’informations, consultez Intégrer des composants Razor ASP.NET Core aux applications ASP.NET Core.

Sections

Pour contrôler le contenu d’une disposition Quand depuis un composant Razor enfant, consultez ASP.NET Core – Sections Blazor.

Ressources supplémentaires

• Disposition dans ASP.NET Core
• Blazor exemples du référentiel GitHub (dotnet/blazor-samples) (procédure de téléchargement)