composant ASP.NET Core Blazor QuickGrid

Le composant QuickGrid est un composant Razor permettant d’afficher rapidement et efficacement les données sous forme tabulaire. QuickGrid fournit un composant de grille de données simple et pratique pour les scénarios d’affichage de grille courants et sert d’architecture de référence et de base de performances pour la création de composants de grille de données. QuickGrid est hautement optimisé et utilise des techniques avancées pour obtenir des performances d’affichage optimales.

Package

Ajoutez une référence de package pour le package Microsoft.AspNetCore.Components.QuickGrid.

Exemple d’application

Pour différentes démonstrations QuickGrid, consultez l’application QuickGrid Blazor un exemple d’application. Le site de démonstration est hébergé sur GitHub Pages. Le site se charge rapidement grâce au pré-rendu statique utilisant le BlazorWasmPrerendering.Buildprojet GitHubgéré par la communauté.

Implémentation QuickGrid

Pour implémenter un composant QuickGrid :

Par exemple, ajoutez le composant suivant pour afficher une grille.

Pour les applications Blazor Web App, le composant QuickGrid doit adopter un mode de rendu interactif pour activer des fonctionnalités interactives, telles que la pagination et le tri.

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

Accédez au composant dans un navigateur au chemin relatif /promotion-grid.

Il n’existe actuellement pas de plans d’extension de QuickGrid avec des fonctionnalités que les grilles commerciales peuvent offrir, par exemple, des lignes hiérarchiques, des colonnes à faire glisser pour réorganiser ou des sélections de plages de type Excel. Si vous avez besoin de fonctionnalités avancées que vous ne souhaitez pas développer par vous-même, continuez à utiliser des grilles tierces.

Trier par colonne

Le composant QuickGrid peut trier les éléments par colonnes. Dans les applications Blazor Web App, le tri nécessite que le composant adopte un mode de rendu interactif.

Ajoutez Sortable="true" (Sortable) à la balise PropertyColumn<TGridItem,TProp> :

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

Dans l’application en cours d’exécution, triez la colonne QuickGrid en sélectionnant le titre de la colonne rendue.

Éléments de page avec un composant Paginator

Le composant QuickGrid peut paginer des données à partir de la source de données. Dans les applications Blazor Web App, la pagination nécessite que le composant adopte un mode de rendu interactif.

Ajoutez une instance PaginationState au bloc @code du composant. Définissez ItemsPerPage sur le nombre d’éléments à afficher par page. Dans l’exemple suivant, l’instance se nomme pagination, et dix éléments par page sont définis :

PaginationState pagination = new PaginationState { ItemsPerPage = 10 };

Affectez la valeur pagination à la propriété Pagination du composant QuickGrid :

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

Pour fournir une IU pour la pagination, ajoutez un composant Paginator au-dessus ou au-dessous du composant QuickGrid. Affectez la valeur pagination à Paginator.State :

<Paginator State="pagination" />

Dans l’application en cours d’exécution, parcourez les éléments à l’aide d’un composant Paginator rendu.

Attributs et styles personnalisés

QuickGrid prend également en charge la transmission de classes de style et d’attributs personnalisés (Class) à l’élément de table rendu :

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

Source de données Entity Framework Core (EF Core)

Utilisez le modèle de fabrique pour résoudre un contexte de base de données EF Core qui fournit des données à un composant QuickGrid. Pour plus d’informations sur la raison pour laquelle le modèle de fabrique est recommandé, consultez ASP.NET Core Blazor avec Entity Framework Core (EF Core).

Une fabrique de contexte de base de données (IDbContextFactory<TContext>) est injectée dans le composant avec la directive @inject. L’approche de fabrique nécessite la suppression du contexte de base de données, de sorte que le composant implémente l’interface IAsyncDisposable avec la directive @implements. Le fournisseur d’éléments pour le composant QuickGrid est un DbSet<T> obtenu à partir du contexte de base de données créé (CreateDbContext) de la fabrique de contexte de base de données injectée.

QuickGrid reconnaît les instances de IQueryable fournies par EF et sait comment résoudre les requêtes de manière asynchrone pour plus d’efficacité.

Ajoutez une référence de package pour le package NuGet Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter.

Appelez AddQuickGridEntityFrameworkAdapter sur la collection de services dans le fichier Program pour inscrire une implémentation de IAsyncQueryExecutor prenant en charge EF :

builder.Services.AddQuickGridEntityFrameworkAdapter();

L’exemple suivant utilise un ExampleTable DbSet<TEntity> (table) d’un contexte de base de données AppDbContext (context) comme source de données pour un composant QuickGrid :

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

Dans le bloc de code (@code) de l’exemple précédent :

• Le champ context détient le contexte de base de données, tapé sous la forme AppDbContext.
• La méthode de cycle de vie OnInitialized affecte un nouveau contexte de base de données (CreateDbContext) au champ context de la fabrique injectée (DbFactory).
• La méthode DisposeAsync asynchrone supprime le contexte de base de données lorsque le composant est supprimé.

Vous pouvez également utiliser n’importe quel opérateur LINQ pris en charge par EF pour filtrer les données avant de le transmettre au paramètre Items.

L’exemple suivant filtre les films par un titre de film entré dans une zone de recherche. Le contexte de base de données est BlazorWebAppMoviesContext et le modèle est Movie. La propriété Title du film est utilisée pour l’opération de filtre.

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

Prise en charge des noms d’affichage

Un titre de colonne peut être affecté en utilisant ColumnBase<TGridItem>.Title dans la balise de PropertyColumn<TGridItem,TProp>. Dans l’exemple de film suivant, le nom « Release Date » est affecté à la colonne pour les données de date de sortie d’un film de la colonne :

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

Cependant, la gestion des titres (noms) de colonne à partir des propriétés du modèle lié est généralement un meilleur choix pour la maintenance d’une application. Un modèle peut contrôler le nom d’affichage d’une propriété avec l’attribut [Display]. Dans l’exemple suivant, le modèle spécifie un nom d’affichage de la date de sortie d’un film « Release Date » pour sa propriété ReleaseDate :

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

Pour permettre au composant QuickGrid d’utiliser le DisplayAttribute.Name, créez une sous-classe pour PropertyColumn<TGridItem,TProp> dans le composant ou dans une classe distincte :

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

Utilisez la sous-classe dans le composant QuickGrid. Dans l’exemple suivant, le DisplayNameColumn précédent est utilisé. Le nom « Release Date » est fourni par l’attribut [Display] dans le modèle : il n’est donc pas nécessaire de spécifier un Title :

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

L’attribut [DisplayName] est également pris en charge :

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

Cependant, l’attribut [Display] est recommandé, car il rend les propriétés supplémentaires disponibles. Par exemple, l’attribut [Display] offre la possibilité d’affecter un type de ressource pour la localisation.

Données distantes

Dans les applications Blazor WebAssembly, il est couramment exigé d’extraire les données à partir d’une API web sur un serveur et basée sur JSON. Pour extraire uniquement les données requises pour la page/fenêtre d’affichage actuelle de données et appliquer des règles de tri ou de filtrage sur le serveur, utilisez le paramètre ItemsProvider.

ItemsProvider peut également être utilisé dans une application Blazor côté serveur si l’application est requise pour interroger un point de terminaison externe. Il peut également être utilisé là où les exigences ne sont pas couvertes par un élément IQueryable.

Fournissez un rappel correspondant au type de délégué GridItemsProvider<TGridItem>, où TGridItem est le type de donnée affichée dans la grille. Le rappel reçoit un paramètre de type GridItemsProviderRequest<TGridItem> qui spécifie l’index de départ, le nombre maximal de lignes et l’ordre de tri des données à retourner. En plus de retourner les éléments correspondants, un nombre total d’éléments (totalItemCount) est également nécessaire pour le bon fonctionnement de la pagination et de la virtualisation.

L’exemple suivant obtient des données à partir de la base de données OpenFDA Food Enforcement publique.

L’élément GridItemsProvider<TGridItem> convertit l’élément GridItemsProviderRequest<TGridItem> en requête visant la base de données OpenFDA. Les paramètres de requête sont traduits dans le format d’URL particulier pris en charge par l’API JSON externe. Il est uniquement possible d’effectuer le tri et le filtrage par le biais des fonctionnalités de tri et de filtrage prises en charge par l’API externe. Le point de terminaison OpenFDA ne prend pas en charge le tri. Ainsi, aucune des colonnes ne sont indiquées comme triables. Toutefois, il prend en charge la fonctionnalité d’ignorer les enregistrements (paramètre skip) et de limiter le retour d’enregistrements (paramètre limit), de sorte que le composant peut activer la virtualisation et rapidement faire défiler des dizaines de milliers d’enregistrements.

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

Pour plus d’informations sur l’appel des API web, consultez Appeler une API web à partir d’une application Blazor ASP.NET Core.

QuickGrid générateur de modèles automatique

Le générateur de modèles automatique QuickGrid génère des modèles de composants Razor avec QuickGrid pour afficher des données à partir d’une base de données.

Le générateur de modèles automatique génère des pages CRUD (Create, Read, Update et Delete) simples basées sur un modèle de données Entity Framework Core. Vous pouvez générer des pages individuelles ou toutes les pages CRUD. Vous sélectionnez la classe de modèle et le DbContext, en créant éventuellement un nouveau DbContext si nécessaire.

Les composants Razor générés sont ajoutés au projet dans un dossier généré nommé d’après la classe de modèle. Le composant Index généré utilise un composant QuickGrid pour afficher les données. Personnalisez les composants générés en fonction des besoins, et activez l’interactivité pour tirer parti des fonctionnalités interactives, comme la pagination, le tri et le filtrage.

Les composants générés par le générateur de modèles automatique nécessitent un rendu côté serveur (SSR) : ils ne sont donc pas pris en charge lors de l’exécution sur WebAssembly.

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