componente ASP.NET Core BlazorQuickGrid

Il QuickGrid componente è un Razor componente per la visualizzazione rapida ed efficiente dei dati in formato tabulare. QuickGrid fornisce un componente griglia di dati semplice e pratico per scenari comuni di rendering della griglia e funge da architettura di riferimento e baseline delle prestazioni per la compilazione di componenti della griglia dati. QuickGrid è altamente ottimizzato e usa tecniche avanzate per ottenere prestazioni di rendering ottimali.

Pacchetto

Aggiungere un riferimento al Microsoft.AspNetCore.Components.QuickGrid pacchetto.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Esempio di app

Per varie QuickGrid dimostrazioni, vedi QuickGrid per Blazor l'app di esempio. Il sito demo è ospitato in GitHub Pages. Il sito viene caricato rapidamente grazie al prerendering statico usando il progetto GitHub gestito dalla BlazorWasmPrerendering.Build community.

QuickGrid implementazione

Per implementare un QuickGrid componente:

• Specificare i tag per il QuickGrid componente nel Razor markup (<QuickGrid>...</QuickGrid>).
• Assegnare un nome a un'origine di dati querybile per la griglia. Usare una delle origini dati seguenti:
  • Items: valore nullable IQueryable<TGridItem>, dove TGridItem è il tipo di dati rappresentato da ogni riga nella griglia.
  • ItemsProvider: callback che fornisce dati per la griglia.
• Class: nome facoltativo della classe CSS. Se specificato, il nome della classe viene incluso nell'attributo class della tabella sottoposta a rendering.
• Theme: nome del tema (valore predefinito: default). Ciò influisce sulle regole di stile che corrispondono alla tabella.
• Virtualize: se true, viene eseguito il rendering della griglia con la virtualizzazione. In genere viene usato insieme allo scorrimento e fa sì che la griglia recuperi e esegua il rendering solo dei dati intorno al viewport di scorrimento corrente. Ciò può migliorare notevolmente le prestazioni durante lo scorrimento tra set di dati di grandi dimensioni. Se si usa Virtualize, è necessario specificare un valore per ItemSize e assicurarsi che ogni riga esegua il rendering con un'altezza costante. In genere, è preferibile non usare Virtualize se la quantità di dati di cui è stato eseguito il rendering è ridotta o se si usa la paginazione.
• ItemSize: applicabile solo quando si usa Virtualize. ItemSize definisce un'altezza prevista in pixel per ogni riga, consentendo al meccanismo di virtualizzazione di recuperare il numero corretto di elementi in modo che corrispondano alle dimensioni di visualizzazione e per garantire uno scorrimento accurato.
• ItemKey: definisce facoltativamente un valore per in @key ogni riga sottoposta a rendering. In genere, viene usato per specificare un identificatore univoco, ad esempio un valore di chiave primaria, per ogni elemento di dati. Ciò consente alla griglia di mantenere l'associazione tra elementi di riga ed elementi di dati in base ai relativi identificatori univoci, anche quando le TGridItem istanze vengono sostituite da nuove copie, ad esempio dopo una nuova query sull'archivio dati sottostante. Se non è impostato, è @key l'istanza TGridItem di .
• Pagination: collega facoltativamente questa TGridItem istanza a un PaginationState modello, causando il recupero della griglia e il rendering solo della pagina corrente di dati. Viene in genere usato insieme a un Paginator componente o a un'altra logica dell'interfaccia utente che visualizza e aggiorna l'istanza fornita PaginationState .
• QuickGrid Nel contenuto figlio (RenderFragment) specificare PropertyColumn<TGridItem,TProp>s, che rappresentano le colonne le cui celle visualizzano TGridItem i valori:
  • Property: definisce il valore da visualizzare nelle celle di questa colonna.
  • Format: specifica facoltativamente una stringa di formato per il valore. Per usare Format è necessario che il TProp tipo implementi IFormattable.
  • Sortable: indica se i dati devono essere ordinabili in base a questa colonna. Il valore predefinito può variare in base al tipo di colonna. Ad esempio, un TemplateColumn<TGridItem> oggetto è ordinabile per impostazione predefinita se viene specificato un SortBy parametro.
  • InitialSortDirection: indica la direzione di ordinamento se IsDefaultSortColumn è true.
  • IsDefaultSortColumn: indica se questa colonna deve essere ordinata per impostazione predefinita.
  • PlaceholderTemplate: se specificato, le griglie virtualizzate usano questo modello per eseguire il rendering delle celle i cui dati non sono stati caricati.
  • HeaderTemplate: modello facoltativo per la cella di intestazione di questa colonna. Se non specificato, il modello di intestazione predefinito include i Titlepulsanti , insieme a eventuali indicatori di ordinamento e opzioni applicabili.
  • Title: testo del titolo per la colonna. Il rendering del titolo viene eseguito automaticamente se HeaderTemplate non viene usato.

Ad esempio, aggiungere il componente seguente per eseguire il rendering di una griglia.

Il componente presuppone che la modalità di rendering Interactive Server (InteractiveServer) venga ereditata da un componente padre o applicata a livello globale all'app, che consente funzionalità interattive. Per l'esempio seguente, l'unica funzionalità interattiva è colonne ordinabili.

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

Accedere al componente in un browser nel percorso /promotion-gridrelativo .

Non esistono piani correnti per l'estensione QuickGrid con funzionalità che le griglie commerciali complete tendono a offrire, ad esempio, righe gerarchiche, colonne di trascinamento del riordinamento o selezioni di intervalli simili a Excel. Se sono necessarie funzionalità avanzate che non si desidera sviluppare autonomamente, continuare a usare griglie di terze parti.

Attributi e stili personalizzati

QuickGrid supporta anche il passaggio di attributi personalizzati e classi di stile all'elemento di tabella di cui è stato eseguito il rendering:

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

Origine dati Entity Framework Core (EF Core)

EF Core's DbContext fornisce una DbSet<TEntity> proprietà per ogni tabella nel database. Fornire la proprietà al Items parametro .

L'esempio seguente usa ( PeopleDbSet<TEntity> tabella) come origine dati:

@inject ApplicationDbContext AppDbContext

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

È anche possibile usare qualsiasi operatore LINQ supportato da EF per filtrare i dati prima di passarli al Items parametro .

L'esempio seguente filtra i documenti in base a un ID categoria:

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

QuickGrid riconosce le istanze fornite da IQueryable ENTITY e sa come risolvere le query in modo asincrono per ottenere efficienza.

Per iniziare, aggiungere un riferimento al Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter pacchetto NuGet.

Nota

Per indicazioni sull'aggiunta di pacchetti alle app .NET, vedere gli articoli sotto Installare e gestire pacchetti in Flusso di lavoro dell'utilizzo di pacchetti (documentazione di NuGet). Confermare le versioni corrette del pacchetto all'indirizzo NuGet.org.

Chiamare AddQuickGridEntityFrameworkAdapter la raccolta di servizi nel Program file per registrare un'implementazione compatibile con IAsyncQueryExecutor Entity Framework:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Supporto dei nomi visualizzati

È possibile assegnare un titolo di colonna usando ColumnBase<TGridItem>.Title il PropertyColumn<TGridItem,TProp>tag del . Nell'esempio seguente alla colonna viene assegnato il nome "Release Date" per i dati relativi alla data di rilascio del film della colonna:

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

Tuttavia, la gestione dei titoli delle colonne (nomi) dalle proprietà del modello associato è in genere una scelta migliore per la gestione di un'app. Un modello può controllare il nome visualizzato di una proprietà con l'attributo [Display]. Nell'esempio seguente, il modello specifica il nome visualizzato della data di rilascio del film "Release Date" per la relativa ReleaseDate proprietà:

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

Per consentire al QuickGrid componente di usare la DisplayAttribute.Namesottoclasse PropertyColumn<TGridItem,TProp> , nel componente o in una classe separata:

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

Usare la sottoclasse nel QuickGrid componente. Nell'esempio seguente viene usato il precedente DisplayNameColumn . Il nome "Release Date" viene fornito dall'attributo[Display] nel modello, quindi non è necessario specificare un Titleoggetto :

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

L'attributo [DisplayName] è supportato anche:

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

Tuttavia, l'attributo [Display] è consigliato perché rende disponibili proprietà aggiuntive. Ad esempio, l'attributo [Display] offre la possibilità di assegnare un tipo di risorsa per la localizzazione.

Dati remoti

Nelle Blazor WebAssembly app, il recupero dei dati da un'API JSWeb basata su ON in un server è un requisito comune. Per recuperare solo i dati necessari per la pagina/viewport corrente dei dati e applicare regole di ordinamento o filtro nel server, usare il ItemsProvider parametro .

ItemsProvider può essere usato anche in un'app lato Blazor server se l'app è necessaria per eseguire query su un endpoint esterno o in altri casi in cui i requisiti non sono coperti da un oggetto IQueryable.

Fornire un callback corrispondente al GridItemsProvider<TGridItem> tipo delegato, dove TGridItem è il tipo di dati visualizzato nella griglia. Al callback viene assegnato un parametro di tipo GridItemsProviderRequest<TGridItem>, che specifica l'indice iniziale, il numero massimo di righe e l'ordinamento dei dati da restituire. Oltre a restituire gli elementi corrispondenti, è necessario anche un conteggio totale degli elementi (totalItemCount) per il corretto funzionamento del paging e della virtualizzazione.

Nell'esempio seguente viene ottenuto dati dal database OpenFDA Food Enforcement pubblico.

GridItemsProvider<TGridItem> Converte l'oggetto GridItemsProviderRequest<TGridItem> in una query sul database OpenFDA. I parametri di query vengono convertiti nel formato URL specifico supportato dall'API ON esterna JS. È possibile eseguire l'ordinamento e il filtro solo tramite l'ordinamento e il filtro supportati dall'API esterna. L'endpoint OpenFDA non supporta l'ordinamento, quindi nessuna delle colonne viene contrassegnata come ordinabile. Tuttavia, supporta l'omissione di record (skip parametro) e la limitazione della restituzione di record (limit parametro ), in modo che il componente possa abilitare la virtualizzazione e scorrere rapidamente decine di migliaia di record.

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

Per altre informazioni sulla chiamata di API Web, vedere Chiamare un'API Web da un'app ASP.NET CoreBlazor.

QuickGrid scaffolder

Lo QuickGrid scaffolder scaffolding dei Razor componenti con QuickGrid per visualizzare i dati da un database.

Lo scaffolder genera pagine crud (Create, Read, Update, Delete) di base basate su un modello di dati Entity Framework Core. È possibile eseguire lo scaffolding di singole pagine o di tutte le pagine CRUD. Selezionare la classe del modello e DbContext, facoltativamente creando un nuovo DbContext oggetto, se necessario.

I componenti scaffolding Razor vengono aggiunti alla cartella del Pages progetto in una cartella generata denominata dopo la classe del modello. Il componente generato Index usa QuickGrid per visualizzare i dati. Personalizzare i componenti generati in base alle esigenze e abilitare l'interattività per sfruttare le funzionalità interattive, ad esempio l'ordinamento e il filtro.

I componenti prodotti dallo scaffolder richiedono il rendering lato server (SSR), quindi non sono supportati durante l'esecuzione in WebAssembly.

Per usare lo scaffolder in Visual Studio, fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Aggiungi>nuovo elemento con scaffolding. Aprire Componente comune>Razor installato.> Selezionare Razor Componenti con Entity Framework (CRUD). Per usare lo scaffolder con l'interfaccia della riga di comando di .NET, vedere ASP.NET strumento di generatore di codice Core ('aspnet-codegenerator').