ASP.NET Core-Komponentenvorlagen in Blazor

Von Robert Haken

In diesem Artikel wird erläutert, wie Komponentenvorlagen eine oder mehrere Benutzeroberflächenvorlagen als Parameter akzeptieren können, die dann wiederum als Teil der Renderlogik der Komponente verwendet werden können.

Komponentenvorlagen

Bei Komponentenvorlagen geht es um Komponenten, die eine oder mehrere Benutzeroberflächenvorlagen als Parameter empfangen, die dann in der Renderlogik der Komponente verwendet werden können. Mithilfe vorlagenbasierter Komponenten können Sie auf höherer Ebene wiederverwendbare Komponenten erstellen. Beispiele:

• Eine Tabellenkomponente, mit der ein Benutzer Vorlagen für die Überschrift, die Zeilen und die Fußzeile einer Tabelle angeben kann
• Eine Listenkomponente, mit der ein Benutzer eine Vorlage für Renderelemente in einer Liste angeben kann
• Eine Komponente auf der Navigationsleiste, mit der eine Vorlage für Startinhalte und Navigationslinks angeben kann.

Eine Komponentenvorlage wird definiert, indem mindestens ein Komponentenparameter des Typs RenderFragment oder RenderFragment<TValue> angegeben wird. Ein Renderfragment stellt dabei ein Segment der Benutzeroberfläche dar, das gerendert werden soll. RenderFragment<TValue> akzeptiert einen Typparameter, der angegeben werden kann, wenn das Renderfragment aufgerufen wird.

Hinweis

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

Häufig werden vorlagenbasierte Komponenten generisch typisiert, wie die folgende TemplatedNavBar-Komponente (TemplatedNavBar.razor) veranschaulicht. Der generische Typ (<T>) im folgenden Beispiel dient dazu, IReadOnlyList<T>-Werte zu rendern. In diesem Fall handelt es sich um eine Liste von Haustieren für eine Komponente, die eine Navigationsleiste mit Links zu einer Detailkomponente für Haustiere anzeigt.

TemplatedNavBar.razor:

@typeparam TItem

<nav class="navbar navbar-expand navbar-light bg-light">
    <div class="container justify-content-start">
        @StartContent
        <div class="navbar-nav">
            @foreach (var item in Items)
            {
                @ItemTemplate(item)
            }
        </div>
    </div>
</nav>

@code {
    [Parameter]
    public RenderFragment? StartContent { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> ItemTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Bei der Verwendung einer Komponentenvorlage werden die Vorlagenparameter mithilfe eines untergeordneten Elements angegeben, das mit den Namen der Parameter übereinstimmt. Im folgenden Beispiel stellen <StartContent>...</StartContent> und <ItemTemplate>...</ItemTemplate> die RenderFragment<TValue>-Vorlagen für StartContent und ItemTemplate der TemplatedNavBar-Komponente bereit.

Geben Sie das Context-Attribut für das Komponentenelement an, wenn Sie den Inhaltsparameternamen für impliziten untergeordneten Inhalt angeben möchten, ohne einen Wrapper um das untergeordnete Elemente erstellen zu müssen. Im folgenden Beispiel steht das Context-Attribut im TemplatedNavBar-Element. Dieses gilt für alle RenderFragment<TValue>-Vorlagenparameter.

Pets1.razor:

@page "/pets-1"

<PageTitle>Pets 1</PageTitle>

<h1>Pets Example 1</h1>

<TemplatedNavBar Items="pets" Context="pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-1")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Alternativ können Sie den Parameternamen mithilfe des Context-Attributs für das untergeordnete RenderFragment<TValue>-Element ändern. Im folgenden Beispiel ist Context auf ItemTemplate anstatt TemplatedNavBar festgelegt.

Pets2.razor:

@page "/pets-2"

<PageTitle>Pets 2</PageTitle>

<h1>Pets Example 2</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate Context="pet">
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-2")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Komponentenargumente vom Typ RenderFragment<TValue> verfügen über einen impliziten Parameter mit dem Namen context, der verwendet werden kann. Im folgenden Beispiel ist Context nicht festgelegt. @context.{PROPERTY} liefert Haustierwerte an die Vorlage, wobei {PROPERTY} eine Pet-Eigenschaft ist:

Pets3.razor:

@page "/pets-3"

<PageTitle>Pets 3</PageTitle>

<h1>Pets Example 3</h1>

<TemplatedNavBar Items="pets">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{context.PetId}?ReturnUrl=%2Fpets-3")" class="nav-link">
            @context.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Bei der Verwendung einer Komponente mit generischem Typ wird der Typparameter nach Möglichkeit abgeleitet. Sie können den Typ jedoch mit einem Attribut explizit angeben, das über einen Namen verfügt, der mit dem Typparameter übereinstimmt. Im vorherigen Beispiel ist dies TItem:

Pets4.razor:

@page "/pets-4"

<PageTitle>Pets 4</PageTitle>

<h1>Pets Example 4</h1>

<TemplatedNavBar Items="pets" Context="pet" TItem="Pet">
    <StartContent>
        <a href="/" class="navbar-brand">PetsApp</a>
    </StartContent>
    <ItemTemplate>
        <NavLink href="@($"/pet-detail/{pet.PetId}?ReturnUrl=%2Fpets-4")" class="nav-link">
            @pet.Name
        </NavLink>
    </ItemTemplate>
</TemplatedNavBar>

@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 2, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 4, Name = "Salem Saberhagen" },
        new Pet { PetId = 7, Name = "K-9" }
    };

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Bei dem in der TemplatedNavBar-Komponente (TemplatedNavBar.razor) angegebenen Beispiel wird davon ausgegangen, dass sich die Items-Auflistung nach dem anfänglichen Rendern nicht ändert oder dass es bei einer Änderung nicht erforderlich ist, den Zustand der in ItemTemplate verwendeten Komponenten/Elemente beizubehalten. Informationen zu vorlagenbasierten Komponenten, bei denen eine solche Verwendung nicht vorausgesagt werden kann, finden Sie im Abschnitten Beibehalten von Beziehungen mit @key.

Beibehalten von Beziehungen mit @key

Vorlagenkomponenten werden häufig zum Rendern von Auflistungen von Elementen verwendet, z. B. von Tabellen oder Listen. In solchen allgemeinen Szenarien kann nicht davon ausgegangen werden, dass Benutzer oder Benutzerinnen zustandsbehaftete Komponenten/Elemente in der Elementvorlagendefinition vermeiden oder dass keine zusätzlichen Änderungen an der Items-Auflistung vorgenommen werden. Für solche vorlagenbasierten Komponenten ist es erforderlich, die Beziehungen mit dem @key-Anweisungsattribut beizubehalten.

Hinweis

Weitere Informationen zum @key-Anweisungsattribut finden Sie unter Beibehalten von Element-, Komponenten- und Modellbeziehungen in ASP.NET Core Blazor.

Die folgende TableTemplate-Komponente (TableTemplate.razor) veranschaulicht eine vorlagenbasierte Komponente, die Beziehungen mit @key beibehält.

TableTemplate.razor:

@typeparam TItem

<table class="table">
    <thead>
        <tr>@TableHeader</tr>
    </thead>
    <tbody>
        @foreach (var item in Items)
        {
            <tr @key="@item">@RowTemplate(item)</tr>
        }
    </tbody>
</table>

@code {
    [Parameter]
    public RenderFragment? TableHeader { get; set; }

    [Parameter, EditorRequired]
    public RenderFragment<TItem> RowTemplate { get; set; } = default!;

    [Parameter, EditorRequired]
    public IReadOnlyList<TItem> Items { get; set; } = default!;
}

Die folgende Pets5-Komponente (Pets5.razor) veranschaulicht die Bedeutung der Schlüsselzuordnung für Daten zum Beibehalten von Modellbeziehungen. In der Komponente führt jede Iteration zum Hinzufügen eines Haustiers in OnAfterRenderAsync dazu, dass Blazor die TableTemplate-Komponente erneut rendert.

Pets5.razor:

@page "/pets-5"

<PageTitle>Pets 5</PageTitle>

<h1>Pets Example 5</h1>

<TableTemplate Items="pets" Context="pet">
    <TableHeader>
        <th>ID</th>
        <th>Name</th>
    </TableHeader>
    <RowTemplate>
        <td><input value="@pet.PetId" /></td>
        <td><input value="@pet.Name" /></td>
    </RowTemplate>
</TableTemplate>


@code {
    private List<Pet> pets = new()
    {
        new Pet { PetId = 1, Name = "Mr. Bigglesworth" },
        new Pet { PetId = 2, Name = "Salem Saberhagen" },
        new Pet { PetId = 3, Name = "K-9" }
    };

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        // Insert new pet every 5 seconds
        if (pets.Count < 10)
        {
            await Task.Delay(5000);
            pets.Insert(0, new Pet() { PetId = pets.Count + 1, Name = "<new pet>" });
            StateHasChanged();
        }
    }

    private class Pet
    {
        public int PetId { get; set; }
        public string? Name { get; set; }
    }
}

Diese Demonstration ermöglicht Ihnen Folgendes:

• Wählen Sie einen <input> aus mehreren gerenderten Tabellenzeilen aus.
• Untersuchen Sie das Verhaltens des Seitenfokus, wenn die Größe der pets-Auflistung automatisch zunimmt.

Ohne das @key-Anweisungsattribut in der TableTemplate-Komponente bleibt der Seitenfokus auf derselben Indexposition (Zeile) der Tabelle, sodass der Fokus bei jedem Hinzufügen eines Haustiers verschoben wird. Um dies zu veranschaulichen, entfernen Sie das @key-Anweisungsattribut und den Wert, starten Sie die App neu, und versuchen Sie, einen Feldwert zu ändern, wenn Elemente hinzugefügt werden.

Zusätzliche Ressourcen

• Bewährte Methoden für die Leistung von Blazor in ASP.NET Core
• Beibehalten von Element-, Komponenten- und Modellbeziehungen in ASP.NET Core Blazor
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)