Blazor-Layouts in ASP.NET Core

In diesem Artikel wird erläutert, wie Sie wiederverwendbare Layoutkomponenten für Blazor-Apps erstellen.

Nützlichkeit von Blazor-Layouts

Einige App-Elemente wie Menüs, Copyrightmeldungen und Firmenlogos sind in der Regel Teil des allgemeinen Erscheinungsbilds. Das Platzieren einer Kopie des Markups für diese Elemente in allen Komponenten einer App ist nicht effizient. Jedes Mal, wenn eines dieser Elemente aktualisiert wird, muss sonst jede Komponente, die das Element verwendet, aktualisiert werden. Dieser Ansatz bringt einen hohen Verwaltungsaufwand mit sich und kann zu inkonsistenten Inhalten führen, wenn eine Aktualisierung versäumt wird. Diese Probleme lassen sich mit Layouts lösen.

Ein Blazor-Layout ist eine Razor-Komponente, die Markup für Komponenten, die darauf verweisen, zur Verfügung stellt. Layouts können Datenbindung, Abhängigkeitsinjektionund andere Funktionen von Komponenten verwenden.

Layoutkomponenten

Erstellen einer Layoutkomponente

So erstellen Sie eine Layoutkomponente

• Erstellen Sie eine Razor-Komponente, die durch eine Razor-Vorlage oder C#-Code definiert wird. Layoutkomponenten, die auf einer Razor-Vorlage basieren, verwenden wie normale Razor-Komponenten die Dateierweiterung .razor. Da Layoutkomponenten von den Komponenten einer App gemeinsam genutzt werden, werden sie normalerweise im Ordner Shared oder Layout der App platziert. Layouts können jedoch an jedem Speicherort platziert werden, auf den die Komponenten zugreifen können, die sie verwenden. Ein Layout kann z. B. in demselben Ordner wie die Komponenten platziert werden, die es verwenden.
• Legen Sie die Komponente so fest, dass sie von LayoutComponentBase erbt. LayoutComponentBase definiert eine Body-Eigenschaft (RenderFragment-Typ) für die gerenderten Inhalte im Layout.
• Verwenden Sie die Razor-Syntax @Body, um die Position im Layoutmarkup anzugeben, an der die Inhalte gerendert werden.

Hinweis

Weitere Informationen zu RenderFragment finden Sie unter ASP.NET Core Razor Komponenten.

Die folgende DoctorWhoLayout-Komponente zeigt die Razor-Vorlage einer Layoutkomponente. Das Layout erbt LayoutComponentBase und legt den @Body zwischen der Navigationsleiste (<nav>...</nav>) und der Fußzeile (<footer>...</footer>) fest.

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

In einer App, die auf Grundlage einer Blazor-Projektvorlage erstellt wurde, ist die MainLayout-Komponente das Standardlayout der App. Das Layout von Blazor übernimmt das Flexbox layout model (MDN documentation) (W3C-Spezifikation).

Die Blazor-CSS-Isolationsfunktion wendet isolierte CSS-Stile auf die MainLayout-Komponente an. Gemäß der Konvention werden die Stile durch das dazugehörige Stylesheet desselben Namens (MainLayout.razor.css) bereitgestellt. Die Stylesheetimplementierung des ASP.NET Core-Frameworks können Sie sich in der ASP.NET Core-Verweisquelle (dotnet/aspnetcore-GitHub-Repository) ansehen:

• Blazor Web App MainLayout.razor.css
• Blazor WebAssembly MainLayout.razor.css

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Anwenden eines Layouts

Layoutnamespace verfügbar machen

Layoutdateispeicherorte und Namespaces wurden im Laufe der Zeit für das Blazor-Framework geändert. Je nach Version von Blazor und Typ der Blazor-App, die Sie erstellen, müssen Sie ggf. den Namespace des Layouts angeben, wenn Sie es verwenden. Wenn Sie auf eine Layoutimplementierung verweisen und das Layout nicht gefunden werden kann, ohne den Namespace des Layouts anzugeben, gehen Sie folgendermaßen vor:

• Fügen Sie der _Imports.razor-Datei eine @using-Anweisung für den Speicherort der Layouts hinzu. Im folgenden Beispiel befindet sich ein Ordner mit Layouts mit dem Namen „Layout“ in einem Components-Ordner, und der Namespace der App lautet „BlazorSample“:

  @using BlazorSample.Components.Layout
  

• Fügen Sie oben in der Komponentendefinition, in der das Layout verwendet wird, eine @using-Anweisung hinzu:

  @using BlazorSample.Components.Layout
  @layout DoctorWhoLayout
  

• Qualifizieren Sie den Namespace des Layouts, in dem er verwendet wird:

  @layout BlazorSample.Components.Layout.DoctorWhoLayout
  

Anwenden eines Layouts auf eine Komponente

Wenden Sie die @layoutRazor-Anweisung an, um ein Layout auf eine routingfähige Razor-Komponente anzuwenden, die über eine @page-Anweisung verfügt. Der Compiler konvertiert @layout in ein LayoutAttribute und wendet das Attribut auf die Komponentenklasse an.

Der Inhalt der folgenden Episodes-Komponente wird an der Stelle des @Body in das DoctorWhoLayout eingefügt.

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>

Das folgende gerenderte HTML-Markup wird vom vorstehenden DoctorWhoLayout und der Episodes-Komponente erstellt. Sonstiges Markup wird nicht angegeben, um sich auf den Inhalt zu beschränken, der von den beiden beteiligten Komponenten bereitgestellt wird:

• Die H1-Überschrift „database“ (<h1>...</h1>) in der Kopfzeile (<header>...</header>), die Navigationsleiste (<nav>...</nav>) sowie die Markeninformationen in der Fußzeile (<footer>...</footer>) stammen aus der DoctorWhoLayout-Komponente.
• Die H2-Überschrift „episodes“ (<h2>...</h2>) und die Episodenliste (<ul>...</ul>) stammen aus der Episodes-Komponente.

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

<nav>
    ...
</nav>

<h2>...</h2>

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

<footer>
    ...
</footer>

Durch direktes Festlegen eines Layouts in einer Komponente wird ein Standardlayout überschrieben:

• Durch eine @layout-Anweisung festgelegt, die aus einer _Imports.razor-Datei importiert wurde, wie im folgenden Abschnitt Anwenden eines Layouts auf einen Ordner mit Komponenten beschrieben wird.
• Als Standardlayout der App festgelegt, wie im Abschnitt Anwenden eines Standardlayouts auf eine App weiter unten in diesem Artikel beschrieben wird.

Anwenden eines Layouts auf einen Ordner mit Komponenten

Alle Ordner einer App können optional eine Vorlagendatei namens _Imports.razor enthalten. Der Compiler enthält die in der Importdatei angegebenen Anweisungen in allen Razor-Vorlagen im gleichen Ordner und rekursiv in allen Unterordnern. Daher wird mit einer _Imports.razor-Datei, die @layout DoctorWhoLayout enthält, sichergestellt, dass alle Komponenten in einem Ordner die DoctorWhoLayout-Komponente verwenden. @layout DoctorWhoLayout muss nicht jeweils allen Razor-Komponenten (.razor) im Ordner und in den Unterordnern hinzugefügt werden.

_Imports.razor:

@layout DoctorWhoLayout
...

Die Datei _Imports.razor ähnelt der Datei _ViewImports.cshtml für Razor-Ansichten und -Seiten, gilt aber spezifisch für Razor-Komponentendateien.

Durch Angabe eines Layouts in _Imports.razor wird ein Layout überschrieben, das als Standard-App-Layout des Routers angegeben wurde. Dies wird im folgenden Abschnitt beschrieben.

Warnung

Fügen Sie der _Imports.razor-Stammdatei keineRazor@layout-Anweisung hinzu. Dies würde zu einer Endlosschleife von Layouts führen. Um das Standardlayout der App zu steuern, legen Sie es in der Komponente Router fest. Weitere Informationen finden Sie im folgenden Abschnitt Anwenden eines Standardlayouts auf eine App.

Hinweis

Die @layoutRazor-Anweisung wendet ein Layout nur auf routingfähige Razor-Komponenten mit einer @page-Anweisung an.

Anwenden eines Standardlayouts auf eine App

Legen Sie das Standardlayout für die App in der RouteView-Komponente der Router-Komponente fest. Verwenden Sie den DefaultLayout-Parameter, um den Layouttyp festzulegen:

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

Im vorherigen Beispiel ist der {LAYOUT}-Platzhalter das Layout (z. B. DoctorWhoLayout wenn der Name der Layoutdatei „DoctorWhoLayout.razor“ lautet). Möglicherweise müssen Sie den Namespace des Layouts je nach .NET-Version und Typ der Blazor-App identifizieren. Weitere Informationen finden Sie im Abschnitt Layoutnamespace verfügbar machen.

Das Festlegen des Layouts als Standardlayout in RouteView der Router-Komponente empfiehlt sich, da Sie das Layout so für einzelne Komponenten oder Ordner überschreiben können, wie in den Abschnitten weiter oben in diesem Artikel erläutert. Wir empfehlen die Verwendung der Router-Komponente, um das Standardlayout der App festzulegen, da dies den universellsten und flexibelsten Ansatz für die Verwendung von Layouts darstellt.

Anwenden eines Layouts auf beliebige Inhalte (LayoutView-Komponente)

Wenn Sie ein Layout für beliebige Inhalte von Razor-Vorlagen festlegen möchten, geben Sie das Layout mit einer LayoutView-Komponente an. Sie können LayoutView in beliebigen Razor-Komponenten verwenden. Im folgenden Beispiel wird eine Layoutkomponente mit dem Namen ErrorLayout für die NotFound-Vorlage (<NotFound>...</NotFound>) der MainLayout-Komponente festgelegt.

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

Möglicherweise müssen Sie die identity des Namespace des Layouts je nach .NET-Version und Typ der Blazor-App feststellen. Weitere Informationen finden Sie im Abschnitt Layoutnamespace verfügbar machen.

Wichtig

Blazor Web Apps verwenden nicht den NotFound-Parameter (<NotFound>...</NotFound>-Markup), der Parameter wird jedoch aus Gründen der Abwärtskompatibilität unterstützt, um eine einschneidende Änderung im Framework zu vermeiden. Die serverseitige ASP.NET Core Middleware-Pipeline verarbeitet Anforderungen auf dem Server. Verwenden Sie serverseitige Techniken, um fehlerhafte Anforderungen zu verarbeiten. Weitere Informationen finden Sie unter ASP.NET Core Blazor-Rendermodi.

Geschachtelte Layouts

Eine Komponente kann auf ein Layout verweisen, das wiederum auf ein anderes Layout verweist. Geschachtelte Layouts werden beispielsweise dazu verwendet, eine Menüstruktur mit mehreren Ebenen zu erstellen.

Im folgenden Beispiel wird die Verwendung von geschachtelten Layouts veranschaulicht. Die Episodes-Komponente, die im Abschnitt Anwenden eines Layouts auf eine Komponente beschrieben wurde, ist die Komponente, die angezeigt werden soll. Die Komponente verweist auf die DoctorWhoLayout-Komponente.

Bei der folgenden DoctorWhoLayout-Komponente handelt es sich um eine abgeänderte Version des Beispiels, das weiter oben in diesem Artikel vorgestellt wurde. Die Kopf- und Fußzeilenelemente wurden entfernt, und das Layout verweist auf ein anderes Layout (ProductionsLayout). Die Episodes-Komponente wird gerendert, wobei @Body im DoctorWhoLayout dargestellt wird.

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";
}

Die ProductionsLayout-Komponente enthält die Layoutelemente der obersten Ebene, in denen sich jetzt die Kopf- (<header>...</header>) und Fußzeilenelemente (<footer>...</footer>) befinden. Das DoctorWhoLayout mit der Episodes-Komponente wird an der Stelle gerendert, an der @Body steht.

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>

Das folgende gerenderte HTML-Markup wird vom vorstehenden geschachtelten Layout erstellt. Sonstiges Markup wird nicht angegeben, um sich auf den geschachtelten Inhalt zu beschränken, der von den drei beteiligten Komponenten bereitgestellt wird:

• Die Kopfzeilen- (<header>...</header>), Produktionsnavigationsleisten- (<nav>...</nav>) und Fußzeilenelemente (<footer>...</footer>) sowie deren Inhalt stammen aus der ProductionsLayout-Komponente.
• Die H1-Überschrift „database“ (<h1>...</h1>), die Navigationsleiste für die Episoden (<nav>...</nav>) und die Markeninformationen (<div>...</div>) stammen aus der DoctorWhoLayout-Komponente.
• Die H2-Überschrift „episodes“ (<h2>...</h2>) und die Episodenliste (<ul>...</ul>) stammen aus der Episodes-Komponente.

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

Freigeben eines Razor Pages-Layouts mit integrierten Komponenten

Wenn routingfähige Komponenten in eine Razor Pages-App integriert werden, kann das freigegebene Layout der App mit den Komponenten verwendet werden. Weitere Informationen finden Sie unter Integrieren von ASP.NET CoreRazor-Komponenten in ASP.NET Core-Apps.

Abschnitte

Informationen zum Steuern des Inhalts in einem Layout über eine untergeordnete Razor-Komponente finden Sie in den Abschnitten zu ASP.NET Core Blazor.

Zusätzliche Ressourcen

• Layout in ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)