Taghilfsprogramm für Komponenten in ASP.NET Core

Die Component Tag-Hilfsprogramm rendert eine Razor-Komponente in einer Razor Pages-Seite oder MVC-Ansicht.

Voraussetzungen

Befolgen Sie die Anleitungen im Abschnitt Verwenden nicht routingfähiger Komponenten in Seiten oder Ansichten des Artikels Integrieren von ASP.NET Core Razor-Komponenten in ASP.NET Core-Apps.

Taghilfsprogramm für Komponenten

Verwenden Sie das Komponententaghilfsprogramm (<component>-Tag) zum Rendern einer Komponente auf einer Seite oder in einer Ansicht.

RenderMode konfiguriert folgende Einstellungen für die Komponente:

• Ob die Komponente zuvor für die Seite gerendert wird
• Ob die Komponente als statische HTML auf der Seite gerendert wird oder ob sie die nötigen Informationen für das Bootstrapping einer Blazor-App über den Benutzer-Agent enthält.

Die Rendermodi der Blazor WebAssembly-App werden in der folgenden Tabelle aufgeführt.

Render Mode	Beschreibung
WebAssembly	Rendert einen Marker für eine Blazor WebAssembly-App zur Einbindung einer interaktiven Komponente, wenn diese im Browser geladen wird. Die Komponente wird nicht vorab gerendert. Diese Option erleichtert das Rendern verschiedener Blazor WebAssembly-Komponenten auf verschiedenen Seiten.
WebAssemblyPrerendered	Rendert die Komponente vorab in statischen HTML-Code und enthält einen Marker für eine Blazor WebAssembly-App zur späteren Verwendung, um die Komponente nach Laden in den Browser interaktiv zu gestalten.

Rendermodi werden in der folgenden Tabelle angezeigt.

Render Mode	Beschreibung
ServerPrerendered	Rendert die Komponente in statischem HTML-Code und enthält eine Markierung für eine serverseitige Blazor-App. Wenn der Benutzer-Agent gestartet wird, wird der Marker zum Bootstrapping einer Blazor-App verwendet.
Server	Rendert eine Markierung für eine serverseitige Blazor-App. Die Ausgabe der -Komponente ist nicht enthalten. Wenn der Benutzer-Agent gestartet wird, wird der Marker zum Bootstrapping einer Blazor-App verwendet.
Static	Rendert die -Komponente in statischem HTML.

Weitere Merkmale sind:

• Mehrere Komponententaghilfsprogramme, die mehrere Razor-Komponenten rendern, sind zulässig.
• Komponenten können nicht dynamisch gerendert werden, nachdem die App gestartet wurde.
• Seiten und Ansichten können zwar Komponenten verwenden, doch das Gegenteil ist nicht der Fall. Komponenten können ansichts- und seitenspezifische Funktionen nicht nutzen, z. B. Teilansichten und Abschnitte. Zum Verwenden der Logik aus einer Teilansicht in einer Komponente müssen Sie die Logik in die Komponente verlagern.
• Das Rendern von Serverkomponenten über eine statische HTML-Seite wird nicht unterstützt.

Die folgende Komponententag-Hilfsprogramm rendert die EmbeddedCounter-Komponente in einer Seite oder Ansicht in einer serverseitigen Blazor-App mit ServerPrerendered:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(EmbeddedCounter)" render-mode="ServerPrerendered" />

Im vorherigen Beispiel wird davon ausgegangen, dass sich die EmbeddedCounter-Komponente im Ordner Components der App befindet. Der Platzhalter {APP ASSEMBLY} ist der Assemblyname der App (z. B. @using BlazorSample.Components).

Das Komponententaghilfsprogramm kann auch Parameter an Komponenten übergeben. Betrachten Sie die folgende ColorfulCheckbox-Komponente, die die Farbe und Größe der Bezeichnung des Kontrollkästchens festlegt.

Components/ColorfulCheckbox.razor:

<label style="font-size:@(Size)px;color:@Color">
    <input @bind="Value"
           id="survey" 
           name="blazor" 
           type="checkbox" />
    Enjoying Blazor?
</label>

@code {
    [Parameter]
    public bool Value { get; set; }

    [Parameter]
    public int Size { get; set; } = 8;

    [Parameter]
    public string? Color { get; set; }

    protected override void OnInitialized()
    {
        Size += 10;
    }
}

Die -KomponentenparameterSize (int) und Color (string) können vom Komponententaghilfsprogramm festgelegt werden:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}.Components

...

<component type="typeof(ColorfulCheckbox)" render-mode="ServerPrerendered" 
    param-Size="14" param-Color="@("blue")" />

Im vorherigen Beispiel wird davon ausgegangen, dass sich die ColorfulCheckbox-Komponente im Ordner Components befindet. Der Platzhalter {APP ASSEMBLY} ist der Assemblyname der App (z. B. @using BlazorSample.Components).

Der folgende HTML-Code wird auf der Seite oder in der Ansicht gerendert:

<label style="font-size:24px;color:blue">
    <input id="survey" name="blazor" type="checkbox">
    Enjoying Blazor?
</label>

Das Übergeben einer Zeichenfolge in Anführungszeichen erfordert einen expliziten Razor-Ausdruck, wie im vorherigen Beispiel für param-Color gezeigt. Das Razor-Analyseverhalten für einen string-Typwert gilt nicht für ein param-*-Attribut, da es sich bei dem Attribut um einen object-Typ handelt.

Alle Arten von Parametern werden mit den folgenden Ausnahmen unterstützt:

• Generische Parameter.
• Nicht serialisierbare Parameter.
• Vererbung in Sammlungsparametern.
• Parameter, deren Typ außerhalb der Blazor WebAssembly-App oder innerhalb einer verzögert geladenen Assembly definiert ist.
• Für den Empfang eines RenderFragment-Delegaten für untergeordneten Inhalt (z. B. param-ChildContent="..."). Für dieses Szenario wird empfohlen, eine Razor-Komponente (.razor) zu erstellen, mit der auf die Komponente verwiesen wird, die mit dem zu übergebenden untergeordneten Inhalt gerendert werden soll, und anschließend die Razor-Komponente über die Seite oder Ansicht mit dem Komponententaghilfsprogramm aufzurufen.

Der Parametertyp muss mit JSON serialisierbar sein. In der Regel bedeutet das, dass der Typ über einen Standardkonstruktor und festlegbare Eigenschaften verfügen muss. Sie können beispielsweise einen Wert für Size und Color im vorherigen Beispiel angeben, da es sich bei den Typen von Size und Color um primitive Typen (int und string) handelt, die vom JSON-Serialisierer unterstützt werden.

Im folgenden Beispiel wird ein Klassenobjekt an die Komponente übergeben:

MyClass.cs:

public class MyClass
{
    public MyClass()
    {
    }

    public int MyInt { get; set; } = 999;
    public string MyString { get; set; } = "Initial value";
}

Die Klasse muss einen öffentlichen parameterlosen Konstruktor besitzen.

Components/ParameterComponent.razor:

<h2>ParameterComponent</h2>

<p>Int: @MyObject?.MyInt</p>
<p>String: @MyObject?.MyString</p>

@code
{
    [Parameter]
    public MyClass? MyObject { get; set; }
}

Pages/MyPage.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using {APP ASSEMBLY}
@using {APP ASSEMBLY}.Components

...

@{
    var myObject = new MyClass();
    myObject.MyInt = 7;
    myObject.MyString = "Set by MyPage";
}

<component type="typeof(ParameterComponent)" render-mode="ServerPrerendered" 
    param-MyObject="@myObject" />

Im vorherigen Beispiel wird davon ausgegangen, dass sich die ParameterComponent-Komponente im Ordner Components der App befindet. Der Platzhalter {APP ASSEMBLY} ist der Assemblyname der App (z. B. @using BlazorSample und @using BlazorSample.Components). MyClass befindet sich im Namespace der App.

Zusätzliche Ressourcen

• Hilfsprogramm „Persist Component State Tag“ in ASP.NET Core
• Vorabrendern von ASP.NET Core Razor-Komponenten
• ComponentTagHelper
• Taghilfsprogramme in ASP.NET Core
• Razor-Komponenten in ASP.NET Core