ASP.NET Core BlazorQuickGrid-Komponente

Die QuickGrid-Komponente ist eine Razor-Komponente zum schnellen und effizienten Anzeigen von Daten in tabellarischer Form. QuickGrid bietet eine einfache und bequeme Datenrasterkomponente für häufige Rasterrenderingszenarien und dient als Referenzarchitektur und Leistungsbaseline zum Erstellen von Datenrasterkomponenten. QuickGrid ist hochgradig optimiert und verwendet erweiterte Techniken, um eine optimale Renderingleistung zu erzielen.

Paket

Fügen Sie einen Paketverweis für das Microsoft.AspNetCore.Components.QuickGrid-Paket hinzu.

Beispiel-App

Verschiedene QuickGrid-Demonstrationen finden Sie unter QuickGrid für Blazor-Beipiel-App. Die Demowebsite wird auf GitHub Pages gehostet. Die Website wird dank statischen Prerenderings mithilfe des von der Community verwalteten BlazorWasmPrerendering.Build-GitHub-Projekts schnell geladen.

QuickGrid-Implementierung

So implementieren Sie eine QuickGrid-Komponente:

Fügen Sie beispielsweise die folgende Komponente hinzu, um ein Raster zu rendern.

Für Blazor Web Apps muss sich die QuickGrid-Komponente in einem interaktiven Rendermodus befinden, um interaktive Features wie Auslagern und Sortierung zu aktivieren.

PromotionGrid.razor:

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

Greifen Sie in einem Browser über den relativen Pfad /promotion-grid auf die Komponente zu.

Es gibt keine aktuellen Pläne, QuickGrid mit Features zu erweitern, die in vollständigen kommerziellen Rastern häufig angeboten werden, z. B. hierarchische Zeilen, durch Ziehen neu anzuordnende Spalten oder Excel-ähnliche Bereichsauswahlen. Wenn Sie erweiterte Features benötigen, die Sie nicht selbst entwickeln möchten, verwenden Sie weiterhin Raster von Drittanbietern.

Sortieren nach Spalten

Die QuickGrid-Komponente kann Elemente nach Spalten sortieren. In Blazor Web Apps muss sich die Komponente in einem interaktiven Rendermodus befinden.

Fügen Sie Sortable="true" (Sortable) zum Tag PropertyColumn<TGridItem,TProp> hinzu:

<PropertyColumn Property="..." Sortable="true" />

Sortieren Sie in der ausgeführten App die QuickGrid-Spalte, indem Sie den gerenderten Spaltentitel auswählen.

Seitenelemente mit einer Paginator-Komponente

Die QuickGrid-Komponente kann Daten aus der Datenquelle auslagern. In Blazor Web Apps muss sich die Komponente zum Auslagern in einem interaktiven Rendermodus befinden.

Fügen Sie dem @code-Block der Komponente eine PaginationState-Instanz hinzu. Legen Sie die ItemsPerPage auf die Anzahl der Elemente fest, die pro Seite angezeigt werden sollen. Im folgenden Beispiel wird die Instanz pagination benannt, und zehn Elemente pro Seite werden festgelegt:

PaginationState pagination = new PaginationState { ItemsPerPage = 10 };

Legen Sie die Pagination-Eigenschaft der QuickGrid-Komponente auf pagination fest:

<QuickGrid Items="..." Pagination="pagination">

Um eine Benutzeroberfläche für die Paginierung bereitzustellen, fügen Sie eine Paginator-Komponente über oder unter der QuickGrid-Komponente hinzu. Legen Sie Paginator.State auf pagination fest:

<Paginator State="pagination" />

Durchlaufen Sie in der ausgeführten App die Elemente mithilfe einer gerenderten Paginator-Komponente.

Benutzerdefiniertes Attribute und Stile

QuickGrid unterstützt auch das Übergeben von benutzerdefinierten Attributen und Stilklassen (Class) an das gerenderte Tabellenelement:

<QuickGrid Items="..." custom-attribute="value" Class="custom-class">

EF Core-Datenquelle (Entity Framework Core)

Verwenden Sie das Factorymuster, um einen EF Core-Datenbankkontext aufzulösen, der Daten für eine QuickGrid-Komponente bereitstellt. Weitere Informationen dazu, warum das Factorymuster empfohlen wird, finden Sie unter ASP.NET Core Blazor mit Entity Framework Core (EF Core).

Eine Datenbankkontextfactory (IDbContextFactory<TContext>) wird mit der @inject-Anweisung in die Komponente eingefügt. Der Factoryansatz erfordert das Entsorgen des Datenbankkontexts, sodass die Komponente die IAsyncDisposable-Schnittstelle mit der @implements-Anweisung implementiert. Der Elementanbieter für die QuickGrid-Komponente ist ein DbSet<T>, das aus dem erstellten Datenbankkontext (CreateDbContext) der eingefügten Datenbankkontextfactory abgerufen wird.

QuickGrid erkennt von EF bereitgestellte IQueryable-Instanzen und weiß, wie Abfragen für mehr Effizienz asynchron aufgelöst werden.

Fügen Sie einen Paketverweis für das Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter-NuGet-Paket hinzu.

Rufen Sie AddQuickGridEntityFrameworkAdapter in der Dienstsammlung in der Datei Program auf, um eine Implementierung von IAsyncQueryExecutor mit EF-Unterstützung zu registrieren:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Im folgenden Beispiel wird eine ExampleTable DbSet<TEntity> (Tabelle) aus einem AppDbContext-Datenbankkontext (context) als Datenquelle für eine QuickGrid-Komponente verwendet:

@using Microsoft.AspNetCore.Components.QuickGrid
@using Microsoft.EntityFrameworkCore
@implements IAsyncDisposable
@inject IDbContextFactory<AppDbContext> DbFactory

...

<QuickGrid ... Items="context.ExampleTable" ...>
    ...
</QuickGrid>

@code {
    private AppDbContext context = default!;

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

Im Codeblock (@code) des vorherigen Beispiels finden Sie Folgendes:

• Das Feld context enthält den Datenbankkontext, der als AppDbContext eingegeben wird.
• Die Lebenszyklusmethode OnInitialized weist dem context-Feld aus der eingefügten Factory (DbFactory) einen neuen Datenbankkontext (CreateDbContext) zu.
• Die asynchrone DisposeAsync-Methode entsorgt den Datenbankkontext, wenn die Komponente beseitigt wird.

Sie können auch einen beliebigen EF-unterstützten LINQ-Operator verwenden, um die Daten zu filtern, bevor Sie sie an den Parameter Items übergeben.

Im folgenden Beispiel werden Filme nach einem Filmtitel gefiltert, der in ein Suchfeld eingegeben wird. Der Datenbankkontext lautet BlazorWebAppMoviesContext und das Modell Movie. Die Title-Eigenschaft des Films wird für den Filtervorgang verwendet.

@using Microsoft.AspNetCore.Components.QuickGrid
@using Microsoft.EntityFrameworkCore
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMoviesContext> DbFactory

...

<p>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</p>

<QuickGrid ... Items="FilteredMovies" ...>
    ...
</QuickGrid>

@code {
    private string titleFilter = string.Empty;
    private BlazorWebAppMoviesContext context = default!;

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    private IQueryable<Movie> FilteredMovies => 
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

Ein funktionierendes Beispiel finden Sie in den folgenden Ressourcen:

• Erstellen eines Lernprogramms für eine Blazor Filmdatenbank-App
• Blazor Beispiel-App für Filmdatenbanken: Wählen Sie den Ordner "Neueste Version" im Repository aus. Der Beispielordner für das Projekt des Lernprogramms heißt BlazorWebAppMovies.

Unterstützung für Anzeigenamen

Ein Spaltentitel kann mithilfe von ColumnBase<TGridItem>.Title im Tag von PropertyColumn<TGridItem,TProp> zugewiesen werden. Im folgenden Filmbeispiel erhält die Spalte den Namen „Release Date“ für die Daten zum Filmstartdatum in der Spalte:

<PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />

Das Verwalten von Spaltentiteln (Namen) aus gebundenen Modelleigenschaften ist in der Regel jedoch die bessere Option für die Verwaltung einer App. Ein Modell kann den Anzeigenamen einer Eigenschaft mit dem [Display]-Attribut steuern. Im folgenden Beispiel gibt das Modell für seine ReleaseDate-Eigenschaft den Anzeigenamen „Release Date“ für das Startdatum eines Films an:

[Display(Name = "Release Date")]
public DateTime ReleaseDate { get; set; }

Damit die QuickGrid-Komponente DisplayAttribute.Name verwenden kann, müssen Sie PropertyColumn<TGridItem,TProp> entweder in der Komponente oder in einer separaten Klasse als Unterklasse definieren:

public class DisplayNameColumn<TGridItem, TProp> : PropertyColumn<TGridItem, TProp>
{
    protected override void OnParametersSet()
    {
        if (Title is null && Property.Body is MemberExpression memberExpression)
        {
            var memberInfo = memberExpression.Member;
            Title = 
                memberInfo.GetCustomAttribute<DisplayNameAttribute>().DisplayName ??
                memberInfo.GetCustomAttribute<DisplayAttribute>().Name ??
                memberInfo.Name;
        }

        base.OnParametersSet();
    }
}

Verwenden Sie die Unterklasse in der Komponente QuickGrid. Im folgenden Beispiel wird die vorangehende DisplayNameColumn verwendet. Der Name „Release Date“ wird vom [Display]-Attribut im Modell bereitgestellt, sodass Title nicht angegeben werden muss:

<DisplayNameColumn Property="movie => movie.ReleaseDate" />

Das [DisplayName]-Attribut wird ebenfalls unterstützt:

[DisplayName("Release Date")]
public DateTime ReleaseDate { get; set; }

Das Attribut [Display] wird jedoch empfohlen, da es zusätzliche Eigenschaften bereitstellt. Beispielsweise bietet das Attribut [Display] die Möglichkeit, einen Ressourcentyp für die Lokalisierung zuzuweisen.

Remotedaten

In Blazor WebAssembly-Apps ist das Abrufen von Daten aus einer JSON-basierten Web-API auf einem Server eine gängige Anforderung. Verwenden Sie den Parameter ItemsProvider, um nur die Daten abzurufen, die für die aktuelle Seite/den Viewport von Daten erforderlich sind, und um Sortier- oder Filterregeln auf dem Server anzuwenden.

ItemsProvider kann auch in einer serverseitigen Blazor-App verwendet werden, wenn die App zum Abfragen eines externen Endpunkts oder in anderen Fällen erforderlich ist, in denen die Anforderungen nicht von IQueryable abgedeckt werden.

Geben Sie einen Rückruf an, der dem Delegattyp GridItemsProvider<TGridItem> entspricht, wobei TGridItem der Datentyp ist, der im Raster angezeigt wird. Dem Rückruf wird ein Parameter vom Typ GridItemsProviderRequest<TGridItem> zugewiesen, der den Startindex, die maximale Zeilenanzahl und die Sortierreihenfolge der zurückzugebenden Daten angibt. Neben der Rückgabe der übereinstimmenden Elemente ist auch eine Gesamtzahl der Elemente (totalItemCount) erforderlich, damit Paging und Virtualisierung ordnungsgemäß funktionieren.

Im folgenden Beispiel werden Daten aus der öffentlichen OpenFDA Food Enforcement-Datenbank abgerufen.

GridItemsProvider<TGridItem> konvertiert GridItemsProviderRequest<TGridItem> in eine Abfrage für die OpenFDA-Datenbank. Abfrageparameter werden in das jeweilige URL-Format übersetzt, das von der externen JSON-API unterstützt wird. Es ist nur möglich, Sortier- und Filtervorgänge über Sortierung und Filterung durchzuführen, die von der externen API unterstützt wird. Der OpenFDA-Endpunkt unterstützt keine Sortierung, sodass keine der Spalten als sortierbar gekennzeichnet ist. Er unterstützt jedoch das Überspringen von Datensätzen (Parameter skip) und das Einschränken der Rückgabe von Datensätzen (Parameter limit), sodass die Komponente die Virtualisierung aktivieren und schnell einen Bildlauf durch Zehntausende von Datensätzen durchführen kann.

FoodRecalls.razor:

@page "/food-recalls"
@inject HttpClient Http
@inject NavigationManager Navigation

<PageTitle>Food Recalls</PageTitle>

<h1>OpenFDA Food Recalls</h1>

<div class="grid" tabindex="-1">
    <QuickGrid ItemsProvider="@foodRecallProvider" Virtualize="true">
        <PropertyColumn Title="ID" Property="@(c => c.Event_Id)" />
        <PropertyColumn Property="@(c => c.State)" />
        <PropertyColumn Property="@(c => c.City)" />
        <PropertyColumn Title="Company" Property="@(c => c.Recalling_Firm)" />
        <PropertyColumn Property="@(c => c.Status)" />
    </QuickGrid>
</div>

<p>Total: <strong>@numResults results found</strong></p>

@code {
    private GridItemsProvider<FoodRecall>? foodRecallProvider;
    private int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = Navigation.GetUriWithQueryParameters(
                "https://api.fda.gov/food/enforcement.json", 
                new Dictionary<string, object?>
            {
                { "skip", req.StartIndex },
                { "limit", req.Count },
            });

            var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
                url, req.CancellationToken);

            return GridItemsProviderResult.From(
                items: response!.Results,
                totalItemCount: response!.Meta.Results.Total);
        };

        numResults = (await Http.GetFromJsonAsync<FoodRecallQueryResult>(
            "https://api.fda.gov/food/enforcement.json"))!.Meta.Results.Total;
    }
}

Weitere Informationen zum Aufrufen von Web-APIs finden Sie unter Aufrufen einer Web-API aus einer ASP.NET Core Blazor-App.

QuickGrid-Gerüst

Das QuickGrid-Gerüst erstellt Gerüste für Razor-Komponenten mit QuickGrid zum Anzeigen von Daten aus einer Datenbank.

Das Gerüst generiert grundlegende Create-, Read-, Update- und Delete-Seiten (CRUD), die auf einem Entity Framework Core-Datenmodell basieren. Sie können ein Gerüst für einzelne Seiten oder alle CRUD-Seiten erstellen. Sie wählen die Modellklasse und DbContext aus, und erstellen optional ein neues DbContext-Modell aus, falls erforderlich.

Die Razor-Gerüstkomponenten werden dem Projekt in einem generierten Ordner hinzugefügt, der nach der Modellklasse benannt ist. Die generierte Index-Komponente verwendet eine QuickGrid-Komponente, um die Daten anzuzeigen. Passen Sie die generierten Komponenten nach Bedarf an, und aktivieren Sie Interaktivität, um interaktive Features wie Auslagern, Sortieren und Filtern zu nutzen.

Die vom Gerüst erzeugten Komponenten erfordern serverseitiges Rendering (SSR), sodass sie bei der Ausführung auf WebAssembly nicht unterstützt werden.

dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.SQLite
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Microsoft.AspNetCore.Components.QuickGrid
dotnet add package Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter

dotnet aspnet-codegenerator blazor CRUD -dbProvider {PROVIDER} -dc {DB CONTEXT CLASS} -m {MODEL} -outDir {PATH}

dotnet aspnet-codegenerator blazor -h

dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.SQLite
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Microsoft.AspNetCore.Components.QuickGrid
dotnet add package Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter

dotnet aspnet-codegenerator blazor CRUD -dbProvider {PROVIDER} -dc {DB CONTEXT CLASS} -m {MODEL} -outDir {PATH}

dotnet aspnet-codegenerator blazor -h

Ein Beispiel für die Verwendung des Gerüsts finden Sie unter Erstellen einer Filmdatenbank-App (Übersicht).For an example use of the QuickGrid scaffolder, see Build a Blazor movie database app (Overview).