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.

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

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:

• Geben Sie Tags für die QuickGrid-Komponente im Razor-Markup (<QuickGrid>...</QuickGrid>) an.
• Benennen Sie eine abfragbare Datenquelle für das Raster. Verwenden Sie eine der folgenden Datenquellen:
  • Items: Ein Nullwerte zulassendes IQueryable<TGridItem>, wobei TGridItem der Datentyp ist, der durch jede Zeile im Raster dargestellt wird.
  • ItemsProvider: Ein Rückruf, der Daten für das Raster bereitstellt.
• Class: Ein optionaler CSS-Klassenname. Falls angegeben, ist der Klassenname im class-Attribut der gerenderten Tabelle enthalten.
• Theme: Ein Designname (Standardwert: default). Dies wirkt sich darauf aus, welche Formatregeln mit der Tabelle übereinstimmen.
• Virtualize: Wenn „true“, wird das Raster mit Virtualisierung gerendert. Dies wird normalerweise in Verbindung mit dem Scrollen verwendet und bewirkt, dass das Raster nur die Daten um den aktuellen Scrollviewport abruft und rendert. Dies kann die Leistung beim Scrollen durch große Datasets erheblich verbessern. Wenn Sie Virtualize verwenden, sollten Sie einen Wert für ItemSize angeben und müssen sicherstellen, dass jede Zeile mit einer konstanten Höhe gerendert wird. Im Allgemeinen sollten Sie Virtualize nicht verwenden, wenn die Menge der gerenderten Daten klein ist, oder Sie die Paginierung verwenden.
• ItemSize: Gilt nur bei Verwendung von Virtualize. ItemSize definiert eine erwartete Höhe in Pixeln für jede Zeile, sodass der Virtualisierungsmechanismus die richtige Anzahl von Elementen abrufen kann, die der Anzeigegröße entspricht, und um genaues Scrollen sicherzustellen.
• ItemKey: Definiert optional einen Wert für @key für jede gerenderte Zeile. In der Regel dient dies dazu, einen eindeutigen Bezeichner, z. B. einen Primärschlüsselwert, für jedes Datenelement anzugeben. So kann das Raster die Zuordnung zwischen Zeilenelementen und Datenelementen auf ihren eindeutigen Bezeichnern basierend beibehalten, auch wenn die TGridItem-Instanzen durch neue Kopien ersetzt werden (z. B. nach einer neuen Abfrage des zugrunde liegenden Datenspeichers). Wenn nicht festgelegt, ist @key die TGridItem-Instanz.
• Pagination: Verknüpft diese TGridItem-Instanz optional mit einem PaginationState-Modell, sodass das Raster nur die aktuelle Datenseite abruft und rendert. Normalerweise wird dies in Verbindung mit einer Paginator-Komponente oder einer anderen Benutzeroberflächenlogik verwendet, die die bereitgestellte PaginationState-Instanz anzeigt und aktualisiert.
• Geben Sie in dem QuickGrid untergeordneten Inhalt (RenderFragment) PropertyColumn<TGridItem,TProp>s an, die TGridItem-Spalten darstellen, deren Zellen Werte anzeigen:
  • Property: Definiert den Wert, der in den Zellen dieser Spalten angezeigt werden soll.
  • Format: Gibt optional eine Formatzeichenfolge für den Wert an. Die Verwendung von Format erfordert, dass der TProp-Typ IFormattable implementiert.
  • Sortable: Gibt an, ob die Daten nach dieser Spalte sortierbar sein sollen. Der Standardwert kann je nach Spaltentyp variieren. Beispielsweise ist eine TemplateColumn<TGridItem> standardmäßig sortierbar, wenn ein SortBy-Parameter angegeben ist.
  • InitialSortDirection: Gibt die Sortierrichtung an, wenn IsDefaultSortColumn gleich true ist.
  • IsDefaultSortColumn: Gibt an, ob diese Spalte standardmäßig sortiert werden sollte.
  • PlaceholderTemplate: Falls angegeben, verwenden virtualisierte Raster diese Vorlage, um Zellen zu rendern, deren Daten nicht geladen wurden.

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

Die Komponente geht davon aus, dass der Interaktive Server-Rendermodus (InteractiveServer) von einer übergeordneten Komponente geerbt wird oder global auf die App angewendet wird, wodurch interaktive Features aktiviert werden. Im folgenden Beispiel sortierbare Spalten die einzige interaktive Funktion.

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();
}

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.

Benutzerdefiniertes Attribute und Stile

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

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

EF Core-Datenquelle (Entity Framework Core)

DbContext von EF Core stellt eine DbSet<TEntity>-Eigenschaft für jede Tabelle in der Datenbank bereit. Geben Sie die Eigenschaft für den Parameter Items an.

Im folgenden Beispiel wird PeopleDbSet<TEntity> (Tabelle) als Datenquelle verwendet:

@inject ApplicationDbContext AppDbContext

<QuickGrid Items="@AppDbContext.People">
    ...
</QuickGrid>

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 Dokumente nach einer Kategorie-ID gefiltert:

<QuickGrid Items="@AppDbContext.Documents.Where(d => d.CategoryId == categoryId)">
    ...
</QuickGrid>

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

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

Hinweis

Einen Leitfaden zum Hinzufügen von Paketen zu .NET-Apps finden Sie in Installieren und Verwalten von Paketen unter Workflow der Nutzung von Paketen (NuGet-Dokumentation). Überprüfen Sie unter NuGet.org, ob die richtige Paketversion verwendet wird.

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();

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 NavManager

<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 {
    GridItemsProvider<FoodRecall>? foodRecallProvider;
    int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = NavManager.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 in Visual Studio erstellt Gerüste für Razor-Komponenten mit QuickGrid zum Anzeigen von Daten aus einer Datenbank.

Um das Gerüst zu verwenden, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie Hinzufügen>Neues Gerüstelement aus. Öffnen Sie die Installierte>Allgemeine>Razor Komponente. Wählen Sie Razor-Komponenten mithilfe von Entity Framework (CRUD) aus.

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 Gerüstkomponenten Razor werden dem Ordner des Pages-Projekts in einem generierten Ordner hinzugefügt, der nach der Modellklasse benannt ist. Die generierte Index-Komponente verwendet QuickGrid, um die Daten anzuzeigen. Passen Sie die generierten Komponenten nach Bedarf an und aktivieren Sie Interaktivität, um interaktive Features wie 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.