Componente QuickGrid do ASP.NET Core Blazor

O componente QuickGrid é um componente Razor para exibir dados de forma rápida e eficiente em formato tabular. O QuickGrid fornece um componente de grade de dados simples e conveniente para cenários comuns de renderização de grade e serve como uma arquitetura de referência e linha de base de desempenho para criar componentes de grade de dados. O QuickGrid é altamente otimizado e usa técnicas avançadas para obter o desempenho ideal de renderização.

Pacote

Adicione uma referência de pacote para o pacote Microsoft.AspNetCore.Components.QuickGrid.

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

Aplicativo de exemplo

Para várias QuickGrid demonstrações, consulte o QuickGrid paraBlazor aplicativo de exemplo. O site de demonstração está hospedado no GitHub Pages. O site é carregado rapidamente graças à pré-geração estática usando o projeto BlazorWasmPrerendering.Build do GitHub mantido pela comunidade.

QuickGrid implementação

Para implementar um componente QuickGrid:

• Especifique as marcas para o componente QuickGrid na marcação Razor (<QuickGrid>...</QuickGrid>).
• Nomeie uma fonte de dados que possa ser consultada para a grade. Use uma das seguintes fontes de dados:
  • Items: um valor anulável IQueryable<TGridItem>, em que TGridItem é o tipo de dados representado por cada linha na grade.
  • ItemsProvider: um retorno de chamada que fornece dados para a grade.
• Class: um nome de classe CSS opcional. Se fornecido, o nome da classe será incluído no atributo class da tabela renderizada.
• Theme: um nome de tema (valor padrão: default). Isso impacta quais regras de estilo correspondem à tabela.
• Virtualize: se for true, a grade será renderizada com virtualização. Normalmente, isso é usado juntamente com a rolagem e faz com que a grade busque e renderize apenas os dados em torno do visor de rolagem atual. Isso pode melhorar muito o desempenho de rolagem em grandes conjuntos de dados. Se usar Virtualize, você deverá fornecer um valor para ItemSize e deverá garantir que cada linha seja renderizada com uma altura constante. Geralmente, é preferível não usar Virtualize se a quantidade de dados renderizados for pequena ou se você estiver usando a paginação.
• ItemSize: aplicável somente ao usar Virtualize. ItemSize define uma altura esperada em pixels para cada linha, permitindo que o mecanismo de virtualização busque o número correto de itens para corresponder ao tamanho da exibição e garantir uma rolagem precisa.
• ItemKey: opcionalmente define um valor para @key em cada linha renderizada. Normalmente, é usado para especificar um identificador exclusivo, como um valor de chave primária, para cada item de dados. Isso permite que a grade preserve a associação entre elementos de linha e itens de dados com base em seus identificadores exclusivos, mesmo quando as instâncias TGridItem são substituídas por novas cópias (por exemplo, após uma nova consulta no armazenamento de dados subjacente). Se não estiver definido, @key será a instância TGridItem.
• Pagination: opcionalmente vincula essa instância TGridItem a um modelo PaginationState, fazendo com que a grade busque e renderize apenas a página de dados atual. Normalmente, é usado em conjunto com um componente Paginator ou alguma outra lógica de interface do usuário que exiba e atualize a instância PaginationState fornecida.
• No conteúdo filho QuickGrid (RenderFragment), especifique PropertyColumn<TGridItem,TProp>s, que representam colunas TGridItem cujas células exibem os valores:
  • Property: define o valor a ser exibido nas células dessa coluna.
  • Format: opcionalmente especifica uma cadeia de caracteres de formato para o valor. Para usar Format, é preciso o tipo TProp para implementar IFormattable.
  • Sortable: indica se os dados devem ser classificados por esta coluna. O valor padrão pode variar de acordo com o tipo de coluna. Por exemplo, um TemplateColumn<TGridItem> é classificável por padrão se qualquer parâmetro SortBy for especificado.
  • InitialSortDirection: indica a direção de classificação se IsDefaultSortColumn for true.
  • IsDefaultSortColumn: indica se essa coluna deve ser classificada por padrão.
  • PlaceholderTemplate: se especificado, as grades virtualizadas usam esse modelo para renderizar células cujos dados não tenham sido carregados.

Por exemplo, adicione o componente a seguir para renderizar uma grade.

O componente pressupõe que o modo de renderização do Servidor Interativo (InteractiveServer) é herdado de um componente pai ou aplicado globalmente ao aplicativo, que possibilita recursos interativos. Para o exemplo a seguir, o único recurso interativo são colunas classificáveis.

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

Acesse o componente em um navegador no caminho relativo /promotion-grid.

No momento, não há planos para estender QuickGrid com recursos que as grades comerciais completas tendem a oferecer, como linhas hierárquicas, colunas de arrastar para reordenar ou seleções de intervalo semelhantes ao Excel. Se você precisar de recursos avançados que não deseja desenvolver por conta própria, continue usando grades de terceiros.

Atributos e estilos personalizados

O QuickGrid também dá suporte à passagem de atributos personalizados e classes de estilo para o elemento de tabela renderizado:

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

Fonte de dados do Entity Framework Core (EF Core)

O DbContext do EF Core fornece uma propriedade DbSet<TEntity> para cada tabela no banco de dados. Forneça a propriedade para o parâmetro Items.

O exemplo a seguir usa a PeopleDbSet<TEntity> (tabela) como a fonte de dados:

@inject ApplicationDbContext AppDbContext

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

Você também pode usar qualquer operador LINQ compatível com EF para filtrar os dados antes de passá-los para o parâmetro Items.

O exemplo a seguir filtra documentos por uma ID de categoria:

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

O QuickGrid reconhece instâncias IQueryable fornecidas por EF e sabe como resolver consultas de forma assíncrona para aumentar a eficiência.

Comece adicionando uma referência de pacote para o pacote NuGet Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter.

Observação

Para obter diretrizes sobre como adicionar pacotes a aplicativos .NET, consulte os artigos em Instalar e gerenciar pacotes no Fluxo de trabalho de consumo de pacotes (documentação do NuGet). Confirme as versões corretas de pacote em NuGet.org.

Chame AddQuickGridEntityFrameworkAdapter na coleta de serviço no arquivo Program para registrar uma implementação de IAsyncQueryExecutor com reconhecimento de EF:

builder.Services.AddQuickGridEntityFrameworkAdapter();

Dados remotos

Em aplicativos Blazor WebAssembly, buscar dados de uma API Web baseada em JSON em um servidor é um requisito comum. Para buscar apenas os dados necessários para a página/visor atual de dados e aplicar regras de classificação ou filtragem no servidor, use o parâmetro ItemsProvider.

ItemsProvider também poderá ser usado em um aplicativo Blazor do lado do servidor se o aplicativo for necessário para consultar um ponto de extremidade externo ou em outros casos em que os requisitos não são cobertos por um IQueryable.

Forneça um retorno de chamada correspondente ao tipo delegado GridItemsProvider<TGridItem>, em que TGridItemé o tipo dos dados exibidos na grade. O retorno de chamada recebe um parâmetro de tipo GridItemsProviderRequest<TGridItem>, que especifica o índice inicial, a contagem máxima de linhas e a ordem de classificação dos dados a serem retornados. Além de retornar os itens correspondentes, uma contagem total de itens (totalItemCount) também é necessária para que a paginação e a virtualização funcionem corretamente.

O exemplo a seguir obtém dados do banco de dados público OpenFDA Food Enforcement.

O GridItemsProvider<TGridItem> converte GridItemsProviderRequest<TGridItem> em uma consulta no banco de dados OpenFDA. Os parâmetros de consulta são convertidos no formato de URL específico compatível com a API JSON externa. Só é possível executar a classificação e a filtragem por meio da classificação e filtragem compatíveis com a API externa. O ponto de extremidade OpenFDA não dá suporte à classificação; portanto, nenhuma das colunas é marcada como classificável. No entanto, ele dá suporte a ignorar registros (parâmetro skip) e limitar o retorno de registros (parâmetro limit), de modo que o componente possa habilitar a virtualização e rolar rapidamente por dezenas de milhares 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 obter mais informações sobre como chamar APIs Web, confira Chamar uma API Web de um aplicativo ASP.NET Core Blazor.

QuickGrid scaffolder

O QuickGrid scaffolder no Visual Studio cria componentes com Razor para exibir dados de um banco de dados.

Para usar o scaffolding, clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Adicionar>Novo Item com Scaffolding. Abra Instalado>Comum>Razor Componente. Selecione Razor Componentes usando o Entity Framework (CRUD).

O scaffolding gera páginas básicas de CRUD (Criação, Leitura, Atualização e Exclusão) com base em um modelo de dados do Entity Framework Core. Você pode criar um scaffolding de páginas individuais ou de todas as páginas CRUD. Selecione a classe de modelo e o DbContext, opcionalmente criando um DbContext, se necessário.

Os componentes Razor com scaffolding são adicionados à pasta Pages do projeto em uma pasta gerada com o mesmo nome da classe de modelo. O componente Index gerado usa QuickGrid para exibir os dados. Personalize os componentes gerados, conforme necessário, e habilite a interatividade para aproveitar os recursos interativos, como classificação e filtragem.

Os componentes produzidos pelo scaffolding exigem a SSR (renderização do lado do servidor), portanto, não há suporte a eles durante a execução no WebAssembly.