Sdílet prostřednictvím

komponenta ASP.NET Core BlazorQuickGrid

  • Článek

Komponenta QuickGrid je komponenta Razor pro rychlé a efektivní zobrazení dat v tabulkové podobě. QuickGrid poskytuje jednoduchou a pohodlnou komponentu datové mřížky pro běžné scénáře vykreslování mřížky a slouží jako referenční architektura a standardní hodnoty výkonu pro vytváření komponent datové mřížky. QuickGrid je vysoce optimalizovaný a používá pokročilé techniky k dosažení optimálního výkonu vykreslování.

Balíček

Přidejte odkaz na Microsoft.AspNetCore.Components.QuickGrid balíček.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Ukázková aplikace

Různé QuickGrid ukázky najdete v quickGridu pro Blazor ukázkovou aplikaci. Ukázkový web je hostovaný na GitHub Pages. Web se rychle načte díky statickému předkreslování pomocí projektu GitHub spravované BlazorWasmPrerendering.Build komunitou.

QuickGrid implementace

QuickGrid Implementace komponenty:

  • Zadejte značky pro komponentu QuickGrid v Razor revizích (<QuickGrid>...</QuickGrid>).
  • Pojmenujte dotazovatelný zdroj dat pro mřížku. Použijte některý z následujících zdrojů dat:
    • Items: Hodnota nullable IQueryable<TGridItem>, kde TGridItem je typ dat reprezentovaný jednotlivými řádky v mřížce.
    • ItemsProvider: Zpětné volání, které poskytuje data pro mřížku.
  • Class: Volitelný název třídy CSS. Je-li k dispozici, název třídy je zahrnut v class atributu vykreslené tabulky.
  • Theme: Název motivu (výchozí hodnota: default). To má vliv na to, která pravidla stylů odpovídají tabulce.
  • Virtualize: Pokud je hodnota true, mřížka se vykreslí pomocí virtualizace. To se obvykle používá ve spojení s posouváním a způsobí, že mřížka načte a vykresluje pouze data kolem aktuálního oblasti zobrazení posuvníku. To může výrazně zlepšit výkon při posouvání velkých datových sad. Pokud použijete Virtualize, měli byste zadat hodnotu a ItemSize zajistit, aby se každý řádek vykreslovat s konstantní výškou. Obecně platí, že není vhodné použít Virtualize , pokud je množství vykreslovaných dat malé nebo pokud používáte stránkování.
  • ItemSize: Lze použít pouze při použití Virtualize. ItemSize definuje očekávanou výšku v pixelech pro každý řádek, což umožňuje mechanismu virtualizace načíst správný počet položek odpovídající velikosti zobrazení a zajistit přesné posouvání.
  • ItemKey: Volitelně definuje hodnotu pro @key každý vykreslený řádek. Obvykle se používá k určení jedinečného identifikátoru, například hodnoty primárního klíče, pro každou položku dat. To umožňuje mřížce zachovat přidružení mezi prvky řádku a datovými položkami na základě jejich jedinečných identifikátorů, i když TGridItem jsou instance nahrazeny novými kopiemi (například po novém dotazu na podkladové úložiště dat). Pokud není nastavená, jedná se @key o TGridItem instanci.
  • OverscanCount: Definuje, kolik dalších položek se má vykreslit před a za viditelnou oblastí, aby se snížila frekvence vykreslování během posouvání. Vyšší hodnoty sice můžou zlepšit plynulost posouvání tím, že vykreslují více položek mimo obrazovku, ale vyšší hodnota může také vést ke zvýšení počáteční doby načítání. Doporučujeme najít rovnováhu na základě velikosti sady dat a požadavků na uživatelské prostředí. Výchozí hodnota je 3. K dispozici pouze při použití Virtualize.
  • Pagination: Volitelně propojte tuto TGridItem instanci s modelem PaginationState , což způsobí načtení a vykreslení mřížky pouze aktuální stránku dat. Obvykle se používá ve spojení s komponentou nebo jinou Paginator logikou uživatelského rozhraní, která zobrazuje a aktualizuje zadanou PaginationState instanci.
  • V podřízeného QuickGrid obsahu (RenderFragment) zadejte PropertyColumn<TGridItem,TProp>hodnoty, které představují TGridItem sloupce, jejichž buňky zobrazují hodnoty:
    • Property: Definuje hodnotu, která se má zobrazit v buňkách tohoto sloupce.
    • Format: Volitelně určuje formátovací řetězec pro hodnotu. Použití Format vyžaduje typ TProp k implementaci IFormattable.
    • Sortable: Určuje, zda mají být data seřazena podle tohoto sloupce. Výchozí hodnota se může lišit podle typu sloupce. Pokud je například zadán libovolný SortBy parametr, TemplateColumn<TGridItem> je možné řadit ve výchozím nastavení.
    • InitialSortDirection: Označuje směr řazení, pokud IsDefaultSortColumn je true.
    • IsDefaultSortColumn: Určuje, jestli má být tento sloupec ve výchozím nastavení seřazený.
    • PlaceholderTemplate: Pokud jsou zadané, virtualizované mřížky používají tuto šablonu k vykreslení buněk, jejichž data nebyla načtena.
    • HeaderTemplate: Volitelná šablona pro buňku záhlaví tohoto sloupce. Pokud není zadáno, obsahuje výchozí šablona záhlaví spolu Titles příslušnými indikátory řazení a tlačítky možností řazení.
    • Title: Text nadpisu sloupce. Název se vykreslí automaticky, pokud HeaderTemplate se nepoužívá.
  • Zadejte značky pro komponentu QuickGrid v Razor revizích (<QuickGrid>...</QuickGrid>).
  • Pojmenujte dotazovatelný zdroj dat pro mřížku. Použijte některý z následujících zdrojů dat:
    • Items: Hodnota nullable IQueryable<TGridItem>, kde TGridItem je typ dat reprezentovaný jednotlivými řádky v mřížce.
    • ItemsProvider: Zpětné volání, které poskytuje data pro mřížku.
  • Class: Volitelný název třídy CSS. Je-li k dispozici, název třídy je zahrnut v class atributu vykreslené tabulky.
  • Theme: Název motivu (výchozí hodnota: default). To má vliv na to, která pravidla stylů odpovídají tabulce.
  • Virtualize: Pokud je hodnota true, mřížka se vykreslí pomocí virtualizace. To se obvykle používá ve spojení s posouváním a způsobí, že mřížka načte a vykresluje pouze data kolem aktuálního oblasti zobrazení posuvníku. To může výrazně zlepšit výkon při posouvání velkých datových sad. Pokud použijete Virtualize, měli byste zadat hodnotu a ItemSize zajistit, aby se každý řádek vykreslovat s konstantní výškou. Obecně platí, že není vhodné použít Virtualize , pokud je množství vykreslovaných dat malé nebo pokud používáte stránkování.
  • ItemSize: Lze použít pouze při použití Virtualize. ItemSize definuje očekávanou výšku v pixelech pro každý řádek, což umožňuje mechanismu virtualizace načíst správný počet položek odpovídající velikosti zobrazení a zajistit přesné posouvání.
  • ItemKey: Volitelně definuje hodnotu pro @key každý vykreslený řádek. Obvykle se používá k určení jedinečného identifikátoru, například hodnoty primárního klíče, pro každou položku dat. To umožňuje mřížce zachovat přidružení mezi prvky řádku a datovými položkami na základě jejich jedinečných identifikátorů, i když TGridItem jsou instance nahrazeny novými kopiemi (například po novém dotazu na podkladové úložiště dat). Pokud není nastavená, jedná se @key o TGridItem instanci.
  • Pagination: Volitelně propojte tuto TGridItem instanci s modelem PaginationState , což způsobí načtení a vykreslení mřížky pouze aktuální stránku dat. Obvykle se používá ve spojení s komponentou nebo jinou Paginator logikou uživatelského rozhraní, která zobrazuje a aktualizuje zadanou PaginationState instanci.
  • V podřízeného QuickGrid obsahu (RenderFragment) zadejte PropertyColumn<TGridItem,TProp>hodnoty, které představují TGridItem sloupce, jejichž buňky zobrazují hodnoty:
    • Property: Definuje hodnotu, která se má zobrazit v buňkách tohoto sloupce.
    • Format: Volitelně určuje formátovací řetězec pro hodnotu. Použití Format vyžaduje typ TProp k implementaci IFormattable.
    • Sortable: Určuje, zda mají být data seřazena podle tohoto sloupce. Výchozí hodnota se může lišit podle typu sloupce. Pokud je například zadán libovolný SortBy parametr, TemplateColumn<TGridItem> je možné řadit ve výchozím nastavení.
    • InitialSortDirection: Označuje směr řazení, pokud IsDefaultSortColumn je true.
    • IsDefaultSortColumn: Určuje, jestli má být tento sloupec ve výchozím nastavení seřazený.
    • PlaceholderTemplate: Pokud jsou zadané, virtualizované mřížky používají tuto šablonu k vykreslení buněk, jejichž data nebyla načtena.
    • HeaderTemplate: Volitelná šablona pro buňku záhlaví tohoto sloupce. Pokud není zadáno, obsahuje výchozí šablona záhlaví spolu Titles příslušnými indikátory řazení a tlačítky možností řazení.
    • Title: Text nadpisu sloupce. Název se vykreslí automaticky, pokud HeaderTemplate se nepoužívá.

Přidejte například následující komponentu pro vykreslení mřížky.

U Blazor Web Apps musí komponenta QuickGrid přijmout interaktivní režim vykreslování, aby bylo možné povolit interaktivní funkce, jako je stránkování a řazení.

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

Přístup ke komponentě v prohlížeči v relativní cestě /promotion-grid.

V současné době se neplánují rozšířit QuickGrid o funkce, které nabízejí plnohodnotné komerční mřížky, například hierarchické řádky, sloupce přetahováním myší nebo výběry oblastí podobné Excelu. Pokud potřebujete pokročilé funkce, které nechcete vyvíjet sami, pokračujte v používání mřížek třetích stran.

Seřadit podle sloupce

Komponenta QuickGrid může řadit položky podle sloupců. Řazení Blazor ve službě Web Apps vyžaduje, aby komponenta přijala interaktivní režim vykreslování.

Přidejte Sortable="true" (Sortable) ke PropertyColumn<TGridItem,TProp> značce:

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

Ve spuštěné aplikaci seřaďte QuickGrid sloupec tak, že vyberete název vykresleného sloupce.

Položky stránky s komponentou Paginator

Komponenta QuickGrid může stránkovat data ze zdroje dat. Ve Blazor službě Web Apps stránkování vyžaduje, aby komponenta přijala interaktivní režim vykreslování.

PaginationState Přidejte instanci do bloku komponenty@code. ItemsPerPage Nastavte počet položek, které se mají zobrazit na stránce. V následujícím příkladu je instance pojmenovaná paginationa na stránce je nastaveno deset položek:

PaginationState pagination = new PaginationState { ItemsPerPage = 10 };

QuickGrid Nastavte vlastnost komponenty Pagination na @pagination:

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

Pokud chcete poskytnout uživatelské rozhraní pro stránkování, přidejte komponentu Paginator nad, pod nebo nad i pod komponentu.QuickGrid Nastavte na Paginator.State :@pagination

<Paginator State="@pagination" />

Ve spuštěné aplikaci můžete procházet položky pomocí vykreslované Paginator komponenty.

Vlastní atributy a styly

QuickGrid také podporuje předávání vlastních atributů a tříd stylů (Class) do elementu vykreslené tabulky:

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

Zdroj dat Entity Framework Core (EF Core)

EF Coreposkytuje DbContext DbSet<TEntity> vlastnost pro každou tabulku v databázi. Zadejte vlastnost parametru Items .

Následující příklad používá People DbSet<TEntity> (tabulka) jako zdroj dat:

@inject ApplicationDbContext AppDbContext

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

Před předáním do parametru můžete také pomocí libovolného operátoru LINQ podporovaného Items systémem EF filtrovat data.

Následující příklad filtruje dokumenty podle ID kategorie:

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

QuickGrid rozpozná instance poskytované IQueryable systémem souborů EF a ví, jak asynchronně řešit dotazy kvůli efektivitě.

Začněte přidáním odkazu na Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter balíček NuGet.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Volání AddQuickGridEntityFrameworkAdapter kolekce služby v Program souboru pro registraci implementace s podporou IAsyncQueryExecutor EF:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Podpora zobrazovaného názvu

Název sloupce lze přiřadit pomocí ColumnBase<TGridItem>.Title PropertyColumn<TGridItem,TProp>značky 's. V následujícím příkladu filmu se sloupci zobrazí název "Release Date" pro data data vydání filmu sloupce:

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

Správa názvů sloupců (názvů) z vlastností vázaného modelu je ale obvykle lepší volbou pro údržbu aplikace. Model může řídit zobrazovaný název vlastnosti s atributem[Display]. V následujícím příkladu model určuje zobrazovaný název data vydání filmu "Release Date" pro jeho ReleaseDate vlastnost:

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

Chcete-li povolitQuickGrid, aby komponenta používala podtřídu DisplayAttribute.NamePropertyColumn<TGridItem,TProp> buď v komponentě, nebo v samostatné třídě:

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

Použijte podtřídu v komponentě QuickGrid . V následujícím příkladu se použije předchozí příklad DisplayNameColumn . Název "Release Date" je poskytován atributem [Display] v modelu, takže není nutné zadávat:Title

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

Tento [DisplayName] atribut je také podporovaný:

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

Atribut se však doporučuje, [Display] protože zpřístupňuje další vlastnosti. Atribut například [Display] nabízí možnost přiřadit typ prostředku pro lokalizaci.

Vzdálená data

V Blazor WebAssembly aplikacích je běžné načítání dat z webového JSrozhraní API založeného na serveru. Pokud chcete načíst pouze data požadovaná pro aktuální stránku nebo oblast zobrazení dat a použít pravidla řazení nebo filtrování na serveru, použijte ItemsProvider parametr.

ItemsProvider lze také použít v aplikaci na straně Blazor serveru, pokud je aplikace nutná k dotazování externího koncového bodu nebo v jiných případech, kdy požadavky nejsou pokryty IQueryable.

Zadejte zpětné volání odpovídající typu delegáta GridItemsProvider<TGridItem> , kde TGridItem je typ dat zobrazených v mřížce. Zpětné volání má parametr typu GridItemsProviderRequest<TGridItem>, který určuje počáteční index, maximální počet řádků a pořadí řazení dat, která se mají vrátit. Kromě vrácení odpovídajících položek se také vyžaduje celkový počet položek (totalItemCount) pro správné fungování stránkování a virtualizace.

Následující příklad získá data z veřejné databáze OpenFDA Food Enforcement.

Převede GridItemsProvider<TGridItem> dotaz GridItemsProviderRequest<TGridItem> na databázi OpenFDA. Parametry dotazu se překládají do konkrétního formátu adresy URL podporovaného externím JSrozhraním ON API. Řazení a filtrování je možné provádět pouze prostřednictvím řazení a filtrování, které podporuje externí rozhraní API. Koncový bod OpenFDA nepodporuje řazení, takže žádný ze sloupců není označený jako seřazený. Podporuje ale přeskočení záznamů (skip parametru) a omezení vrácení záznamů (limit parametru), aby komponenta mohla povolit virtualizaci a rychle procházet desítky tisíc záznamů.

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

Další informace o volání webových rozhraní API najdete v tématu Volání webového rozhraní API z aplikace ASP.NET CoreBlazor.

QuickGrid scaffolder

Scaffolder QuickGrid scaffolds Razor components with QuickGrid to display data from a database.

Scaffolder generuje základní stránky Create, Read, Update a Delete (CRUD) na základě datového modelu Entity Framework Core. Můžete vygenerovat jednotlivé stránky nebo všechny stránky CRUD. V případě potřeby vyberete třídu modelu a DbContextvolitelně vytvoříte novou DbContext .

Vygenerované Razor komponenty se přidají do vygenerované složky projektu pojmenované po třídě modelu. Vygenerovaná Index komponenta používá komponentu QuickGrid k zobrazení dat. Přizpůsobte si vygenerované komponenty podle potřeby a povolte interaktivitu, abyste mohli využívat interaktivní funkce, jako je stránkování, řazení a filtrování.

Komponenty vytvořené scaffolderem vyžadují vykreslování na straně serveru (SSR), takže se při spuštění na WebAssembly nepodporují.

Klikněte pravým tlačítkem myši na Components/Pages složku a vyberte Přidat>novou vygenerovanou položku.

V dialogovém okně Přidat novou položku uživatelského rozhraní se otevře >nainstalovaná společná>Razor komponenta, vyberte Razor Komponenty využívající Entity Framework (CRUD). Vyberte tlačítko Přidat.

Dokončete dialogové okno Přidat Razor komponenty pomocí entity Framework (CRUD):

  • Rozevírací seznam Šablona obsahuje další šablony pro konkrétně vytváření, úpravy, odstraňování, podrobnosti a součásti seznamu. Tento rozevírací seznam je užitečný v případě, že potřebujete vytvořit pouze konkrétní typ vygenerovaného komponenty do třídy modelu. Pokud chcete vygenerovat úplnou sadu komponent, ponechte rozevírací seznam Šablony nastavený na CRUD.
  • V rozevíracím seznamu Třída modelu vyberte třídu modelu. Vytvoří se složka pro vygenerované komponenty z názvu modelu (pokud je třída modelu pojmenována Movie, složka se automaticky jmenuje MoviePages).
  • V případě třídy DbContext vyberte existující kontext databáze nebo vyberte + tlačítko (znaménko plus) a modální dialogové okno Přidat kontext dat pro přidání nového kontextu databáze.
  • Po zavření dialogového okna modelu se rozevírací seznam zprostředkovatele databáze nastaví na SQL Server. Můžete vybrat vhodného zprostředkovatele pro databázi, kterou používáte. Mezi možnosti patří SQL Server, SQLite, PostgreSQL a Azure Cosmos DB.
  • Vyberte Přidat.