Teilansichten in ASP.NET Core

Von Steve Smith, Maher JENDOUBI, Rick Anderson und Scott Sauber

Eine Teilansicht ist eine Razor-Markupdatei (.cshtml) ohne @page-Direktive, die HTML-Ausgabe innerhalb der gerenderten Ausgabe einer anderen Markupdatei rendert.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Wann werden Teilansichten verwendet?

Teilansichten bieten eine effektive Möglichkeit, um Folgendes zu erreichen:

• Aufteilen großer Markupdateien in kleinere Komponenten.

  In einer großen, komplexen Markupdatei, die aus mehreren logischen Teilen besteht, bringt es Vorteile mit sich, mit jeder einzelnen Komponente isoliert in einer Teilansicht zu arbeiten. Der Code in der Markupdatei ist verwaltbar, weil das Markup nur die allgemeine Seitenstruktur und Verweise auf Teilansichten enthält.

• Verringern der Duplizierung von allgemeinem Markupinhalt in Markupdateien.

  Wenn die gleichen Markupelemente in verschiedenen Markupdateien verwendet werden, entfernt eine Teilansicht die Duplizierung von Markupinhalten in einer Teilansichtsdatei. Wenn das Markup in der Teilansicht geändert wird, wird die gerenderte Ausgabe der Markupdateien aktualisiert, die die Teilansicht verwenden.

Teilansichten sollte nicht verwendet werden, um allgemeine Layoutelemente zu verwalten. Häufig verwendete Layoutelemente müssen in _Layout.cshtml-Dateien angegeben werden.

Verwenden Sie keine Teilansicht, wenn für das Rendern des Markups eine komplexe Renderinglogik oder Codeausführung erforderlich ist. Verwenden Sie anstelle einer Teilansicht eine Ansichtskomponente.

Deklarieren von Teilansichten

Verweisen auf eine Teilansicht

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

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

Verwenden einer Teilansicht in einer Markupdatei

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

Asynchrones HTML-Hilfsprogramm

Wenn Sie ein HTML-Hilfsprogramm verwenden, stellt das Verwenden von PartialAsync eine bewährte Methode dar. PartialAsync gibt einen IHtmlContent-Typ in einem Task<TResult> als Wrapper zurück. Sie können auf die Methode verweisen, indem Sie dem erwarteten Aufruf das Zeichen @ als Präfix voranstellen:

@await Html.PartialAsync("_PartialName")

Wenn die Dateierweiterung vorhanden ist, verweist das HTML-Hilfsprogramm auf eine Teilansicht, die sich im gleichen Ordner wie die Markupdatei befinden muss, die die Teilansicht aufruft:

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

Im folgende Beispiel wird aus dem Stammverzeichnis der App auf eine Teilansicht verwiesen. Pfade, die mit einer Tilde und einem Schrägstrich (~/) oder einem Schrägstrich (/) beginnen, verweisen auf den Stamm der App:

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

Das folgende Beispiel verweist auf eine Teilansicht mit einem relativen Pfad:

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

Alternativ können Sie eine Teilansicht auch mit RenderPartialAsync rendern. Diese Methode gibt keinen IHtmlContent zurück. Sie streamt die gerenderte Ausgabe direkt an die Antwort. Da die Methode kein Ergebnis zurückgibt, muss sie in einem Razor-Codeblock aufgerufen werden:

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

Da RenderPartialAsync gerenderte Inhalte streamt, bietet diese Vorgehensweise in einigen Szenarien eine bessere Leistung. In leistungskritischen Situationen sollten Sie die Seite mit beiden Ansätzen einem Benchmarktest unterziehen und den Ansatz verwenden, der eine schnellere Antwort generiert.

Synchrones HTML-Hilfsprogramm

Partial und RenderPartial sind die synchronen Entsprechungen von PartialAsync bzw. RenderPartialAsync. Diese synchronen Entsprechungen werden nicht empfohlen, da sie in manchen Szenarien zu einem Deadlock führen können. Die synchronen Methoden sollen in einem zukünftigen Release entfernt werden.

Ermittlung von Teilansichten

Wenn auf eine Teilansicht anhand des Namens ohne eine Dateierweiterung verwiesen wird, werden die folgenden Speicherorte in der angegebenen Reihenfolge durchsucht:

Für die Ermittlung von Teilansichten gelten die folgenden Konventionen:

• Unterschiedliche Teilansichten mit dem gleichen Dateinamen sind zulässig, wenn sich die Teilansichten in verschiedenen Ordnern befinden.
• Wenn auf eine Teilansicht über den Namen ohne Dateierweiterung verwiesen wird und die Teilansicht sowohl im Ordner des Aufrufers als auch im Ordner Shared vorhanden ist, stellt die Teilansicht im Ordner des Aufrufers die Teilansicht bereit. Wenn die Teilansicht nicht im Ordner des Aufrufers vorhanden ist, wird die Teilansicht aus dem Ordner Shared bereitgestellt. Teilansichten im Ordner Shared werden als Freigegebene Teilansichten oder Standardteilansichten bezeichnet.
• Teilansichten können verkettet werden: Eine Teilansicht kann eine andere Teilansicht aufrufen, wenn durch den Aufruf kein Zirkelbezug entsteht. Relative Pfade sind immer relativ zur aktuellen Datei, nicht zum Stamm- oder übergeordneten Verzeichnis der Datei.

Zugriff auf Daten aus Teilansichten

Wenn eine Teilansicht instanziiert wird, erhält sie eine Kopie des ViewData-Wörterbuchs der übergeordneten Ansicht. An den Daten vorgenommene Änderungen in der Teilansicht werden in der übergeordneten Ansicht nicht beibehalten. Ein ViewData-Wörterbuch, das in einer Teilansicht verändert wird, geht verloren, wenn die Teilansicht eine Rückgabe ausgibt.

Das folgende Beispiel zeigt, wie eine Instanz von ViewDataDictionary an eine Teilansicht übergeben wird:

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

Außerdem können Sie ein Modell an eine Teilansicht übergeben. Das Modell kann ein benutzerdefiniertes Objekt sein. Sie können ein Modell mit PartialAsync (rendert einen Inhaltsblock für den Aufrufer) oder RenderPartialAsync (streamt den Inhalt in die Ausgabe) übergeben:

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

Das folgende Markup in der Beispiel-App zeigt die Views/Articles/Read.cshtml-Ansicht. Die Ansicht enthält die zwei Teilansichten. Die zweite Teilansicht übergibt ein Modell und ViewData an die Teilansicht. Die ViewDataDictionary-Konstruktorüberladung wird verwendet, um ein neues ViewData-Wörterbuch zu übergeben, während das vorhandene ViewData-Wörterbuch beibehalten wird.

@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 ist die erste Teilansicht, auf die in der Read.cshtml-Markupdatei verwiesen wird:

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

Views/Articles/_ArticleSection.cshtml ist die zweite Teilansicht, auf die in der Read.cshtml-Markupdatei verwiesen wird:

@using PartialViewsSample.ViewModels
@model ArticleSection

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

Die Teilansichten werden zur Laufzeit in der gerenderten Ausgabe der übergeordneten Markupdatei gerendert, die wiederum in der freigegebenen Datei _Layout.cshtml gerendert wird. Die erste Teilansicht rendert den Namen des Artikelautors und das Erscheinungsdatum:

Abraham Lincoln

Diese Teilansicht aus dem <Dateipfad der freigegebenen Teilansicht>. 11/19/1863 12:00:00 AM

Die zweite Teilansicht rendert die Abschnitte des Artikels:

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

Zusätzliche Ressourcen