Componentes BlazorQuickGrid de ASP.NET Core

El componente QuickGrid es un componente Razor para mostrar datos de forma rápida y eficaz en formato tabular. QuickGrid proporciona un componente de la cuadrícula de datos que resulta conveniente y simple para escenarios de representación de cuadrículas comunes y sirve de arquitectura de referencia y línea de base de rendimiento para crear componentes de cuadrícula de datos. QuickGrid está altamente optimizado y usa técnicas avanzadas para lograr un rendimiento óptimo de representación.

Paquete

Agregue una referencia de paquete para el paquete Microsoft.AspNetCore.Components.QuickGrid.

Nota:

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulte los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (NuGet documentación). Confirme las versiones correctas del paquete en NuGet.org.

Aplicación de ejemplo

Para ver varias demostraciones de QuickGrid, consulte QuickGrid para la Blazor aplicación de ejemplo. El sitio de demostración se hospeda en GitHub Pages. El sitio se carga rápidamente gracias a la representación previa estática mediante el proyecto de GitHub BlazorWasmPrerendering.Build mantenido por la comunidad.

Implementación de QuickGrid

Para implementar un componente QuickGrid:

• Especifique etiquetas para el componente QuickGrid en el marcado Razor (<QuickGrid>...</QuickGrid>).
• Asigne un nombre a un origen de datos consultable para la cuadrícula. Use cualquiera de los siguientes orígenes de datos:
  • Items: IQueryable<TGridItem> que admite un valor NULL, donde TGridItem es el tipo de datos representado por cada fila de la cuadrícula.
  • ItemsProvider: devolución de llamada que proporciona datos para la cuadrícula.
• Class: un nombre de clase CSS opcional. Si se proporciona, el nombre de clase se incluye en el atributo class de la tabla representada.
• Theme: un nombre de tema (valor predeterminado: default). Esto afecta a las reglas de estilo que coinciden con la tabla.
• Virtualize: si es true, la cuadrícula se representa con virtualización. Esta acción se lleva a cabo normalmente junto con el desplazamiento y hace que la cuadrícula capture y represente solo los datos alrededor de la ventanilla de desplazamiento actual. Esto puede hacer que el rendimiento mejore considerablemente al desplazarse por grandes conjuntos de datos. Si usa Virtualize, debe proporcionar un valor para ItemSize y debe asegurarse de que cada fila se representa con un alto constante. Por lo general, es preferible no usar Virtualize si la cantidad de datos representados es pequeña o si usa paginación.
• ItemSize: solo es aplicable cuando se usa Virtualize. ItemSize define un alto esperado en píxeles para cada fila, lo que permite que el mecanismo de virtualización capture el número correcto de elementos para que coincida con el tamaño de pantalla y para garantizar un desplazamiento preciso.
• ItemKey: define opcionalmente un valor para @key en cada fila representada. Normalmente, se usa para especificar un identificador único, como un valor de clave principal, para cada elemento de datos. Esto permite que la cuadrícula conserve la asociación entre elementos de fila y elementos de datos en función de sus identificadores únicos, incluso cuando las instancias TGridItem se reemplazan por nuevas copias (por ejemplo, después de una nueva consulta en el almacén de datos subyacente). Si no se establece, @key es la instancia de TGridItem.
• Pagination: opcionalmente vincula esta instancia TGridItem con un modelo PaginationState, lo que hace que la cuadrícula capture y represente solo la página actual de datos. Normalmente se usa junto con un componente Paginator o con alguna otra lógica de interfaz de usuario que muestra y actualiza la instancia PaginationState proporcionada.
• En el contenido secundario QuickGrid (RenderFragment), especifique PropertyColumn<TGridItem,TProp>, que representan columnas TGridItem cuyas celdas muestran valores:
  • Property: define el valor que se va a mostrar en las celdas de esta columna.
  • Format: opcionalmente especifica una cadena de formato para el valor. El uso de Format requiere que el tipo TProp implemente IFormattable.
  • Sortable: indica si esta columna debe poder ordenar los datos. El valor predeterminado puede variar según el tipo de columna. Por ejemplo, se puede ordenar TemplateColumn<TGridItem> de forma predeterminada si se especifica algún parámetro SortBy.
  • InitialSortDirection: indica la dirección de ordenación si IsDefaultSortColumn es true.
  • IsDefaultSortColumn: indica si esta columna debe ordenarse de forma predeterminada.
  • PlaceholderTemplate: si se especifica, las cuadrículas virtualizadas usan esta plantilla para representar celdas cuyos datos no se han cargado.

Por ejemplo, agregue el siguiente componente para representar una cuadrícula.

El componente supone que el modo de representación del servidor interactivo (InteractiveServer) se hereda de un componente primario o se aplica globalmente a la aplicación, lo que permite características interactivas. En el ejemplo siguiente, la única característica interactiva es columnas ordenables.

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

Acceda al componente en un explorador en la ruta de acceso relativa /promotion-grid.

En este momento, no se prevén ampliaciones de QuickGrid con características que las cuadrículas comerciales totalmente desarrolladas tienden a ofrecer, por ejemplo: filas jerárquicas, columnas que se pueden arrastrar para reorganizar o selecciones de intervalos similares a Excel. Si necesita características avanzadas que no desea desarrollar por su cuenta, siga usando cuadrículas de terceros.

Atributos y estilos personalizados

QuickGrid también admite el paso de atributos personalizados y clases de estilo al elemento de tabla representado:

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

Origen de datos de Entity Framework Core (EF Core)

El DbContext de EF Core proporciona una propiedad DbSet<TEntity> para cada tabla de la base de datos. Proporcione la propiedad al parámetro Items.

En el ejemplo siguiente se usa PeopleDbSet<TEntity> (tabla) como origen de datos:

@inject ApplicationDbContext AppDbContext

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

También puede usar cualquier operador LINQ compatible con EF para filtrar los datos antes de pasarlos al parámetro Items.

En el ejemplo siguiente se filtran los documentos por un identificador de categoría:

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

QuickGrid reconoce las instancias de IQueryable proporcionadas por EF y sabe cómo resolver consultas de forma asincrónica para lograr una eficacia.

Comience agregando una referencia de paquete para el Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter paquete NuGet.

Nota:

Para obtener instrucciones sobre cómo agregar paquetes a aplicaciones .NET, consulte los artículos de Instalación y administración de paquetes en Flujo de trabajo de consumo de paquetes (NuGet documentación). Confirme las versiones correctas del paquete en NuGet.org.

Llame a AddQuickGridEntityFrameworkAdapter en la colección de servicios en el archivo Program para registrar una implementación de IAsyncQueryExecutor compatible con EF:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Datos remotos

En aplicaciones Blazor WebAssembly, capturar datos de una API web basada en JSON en un servidor es un requisito común. Para capturar solo los datos necesarios para la página o ventanilla actuales de los datos y aplicar reglas de ordenación o filtrado en el servidor, use el parámetro ItemsProvider.

ItemsProvider también se puede usar en una aplicación de Blazor del lado servidor si la aplicación es necesaria para consultar un punto de conexión externo o en otros casos en los que un IQueryable no cubre los requisitos.

Proporcione una devolución de llamada que coincida con el tipo de delegado GridItemsProvider<TGridItem>, donde TGridItem es el tipo de datos que se muestran en la cuadrícula. La devolución de llamada recibe un parámetro de tipo GridItemsProviderRequest<TGridItem>, que especifica el índice de inicio, el número máximo de filas y el orden de ordenación de los datos que se van a devolver. Además de devolver los elementos coincidentes, también se requiere un recuento total de elementos (totalItemCount) para que la paginación y la virtualización funcionen correctamente.

En el ejemplo siguiente se obtienen datos de la base de datos pública OpenFDA Food Enforcement.

El GridItemsProvider<TGridItem> convierte el GridItemsProviderRequest<TGridItem> en una consulta en la base de datos de OpenFDA. Los parámetros de consulta se traducen en el formato de dirección URL determinado admitido por la API JSON externa. Solo es posible realizar la ordenación y el filtrado mediante la ordenación y el filtrado admitidos por la API externa. El punto de conexión de OpenFDA no admite la ordenación, por lo que ninguna de las columnas se marca como ordenable. Sin embargo, admite la omisión de registros (parámetro skip) y la limitación del retorno de registros (parámetro limit), por lo que el componente puede habilitar la virtualización y desplazarse rápidamente a través de decenas de miles de registros.

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

Para obtener más información sobre cómo llamar a las API web, consulte Llamada a una API web desde una aplicación Blazor de ASP.NET Core.

Scaffolder QuickGrid

El scaffolder QuickGrid agrupa componentes Razor con QuickGrid para mostrar datos de una base de datos.

El proveedor de scaffolding genera páginas básicas de creación, lectura, actualización y eliminación (CRUD) basadas en un modelo de datos de Entity Framework Core. Puede aplicar scaffolding a páginas individuales o a todas las páginas CRUD. Seleccione la clase de modelo y DbContext, opcionalmente para crear una instancia deDbContext si es necesario.

Los componentes Razor con scaffolding se agregan a la carpeta Pages del proyecto en una carpeta generada con el mismo nombre que la clase de modelo. El componente Index generado usa QuickGrid para mostrar los datos. Personalice los componentes generados según sea necesario y habilite la interactividad para sacar provecho de las características interactivas, como las de ordenación y filtrado.

Los componentes generados por el proveedor de scaffolding necesitan la representación del lado servidor (SSR), por lo que no se admiten al ejecutarse en WebAssembly.

Para usar el scaffolder en Visual Studio, haga clic con el botón derecho en el proyecto en el Explorador de soluciones y seleccione Agregar>Nuevo elemento con scaffold. Abra Instalados>Comunes>Componente Razor. Seleccione Componentes Razor con Entity Framework (CRUD). Para usar el scaffolder con la CLI de .NET, consulte Herramienta generadora de código de ASP.NET Core ("aspnet-codegenerator").