Esta não é a versão mais recente deste artigo. Para a versão atual, consulte a versão .NET 9 deste artigo.
Importante
Estas informações referem-se a um produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.
O componente QuickGrid é um componente Razor para exibir dados de forma rápida e eficiente em forma de tabela.
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 a criação de componentes de grade de dados.
QuickGrid é altamente otimizado e usa técnicas avançadas para alcançar um desempenho de renderização ideal.
Especifique etiquetas para o componente QuickGrid na marcação Razor (<QuickGrid>...</QuickGrid>).
Indique uma fonte de dados consultável para a grelha. Use ou de uma das seguintes fontes de dados:
Items: Um IQueryable<TGridItem>anulável , onde TGridItem é o tipo de dados representado por cada linha na grade.
ItemsProvider: Um retorno de chamada que fornece dados para a grelha.
Class: Um nome de classe CSS opcional. Se fornecido, o nome da classe é incluído no atributo class da tabela renderizada.
Theme: Um nome de tema (valor padrão: default). Isso afeta quais regras de estilo correspondem à tabela.
Virtualize: Se verdadeiro, a grelha é renderizada com virtualização. Isso normalmente é usado em conjunto com a rolagem e faz com que a grelha busque e renderize apenas os dados ao redor da janela de visualização de rolagem atual. Isso pode melhorar muito o desempenho ao rolar por grandes conjuntos de dados. Se você usar Virtualize, você deve fornecer um valor para ItemSize e deve 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 paginação.
ItemSize: Aplicável apenas quando se utiliza 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 tela e garantir uma rolagem precisa.
ItemKey: Opcionalmente, define um valor para @key em cada linha renderizada. Normalmente, isso é 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, a instância @key é a TGridItem.
OverscanCount: Define quantos itens adicionais renderizar antes e depois da região visível para reduzir a frequência de renderização durante a rolagem. Embora valores mais altos possam melhorar a suavidade da rolagem ao renderizar mais itens fora da tela, um valor mais alto também pode resultar em um aumento nos tempos de carregamento iniciais. Recomenda-se encontrar um equilíbrio com base no tamanho do conjunto de dados e nos requisitos de experiência do usuário. O valor padrão é 3. Disponível apenas quando se utiliza Virtualize.
Pagination: Opcionalmente, vincula essa instância TGridItem a um modelo PaginationState, fazendo com que a grade busque e renderize apenas a página atual de dados. Isso normalmente é usado em conjunto com um componente Paginator ou alguma outra lógica de interface do usuário que exibe e atualiza a instância de PaginationState fornecida.
Property: Define o valor a ser exibido nas células desta coluna.
Format: Opcionalmente, especifica uma cadeia de caracteres de formato para o valor. Para usar Format, é necessário que o tipo TProp implemente IFormattable.
Sortable: Indica se os dados devem ser classificáveis por esta coluna. O valor padrão pode variar de acordo com o tipo de coluna. Por exemplo, um TemplateColumn<TGridItem> é ordenado quando qualquer parâmetro SortBy é especificado.
IsDefaultSortColumn: Indica se esta coluna deve ser classificada por padrão.
PlaceholderTemplate: Se especificado, as grades virtualizadas usam esse modelo para renderizar células cujos dados não foram carregados.
HeaderTemplate: Um modelo opcional para a célula de cabeçalho desta coluna. Se não for especificado, o modelo de cabeçalho padrão incluirá o Title, juntamente com quaisquer indicadores de classificação e botões de opções aplicáveis.
Title: Texto do título da coluna. O título é renderizado automaticamente se HeaderTemplate não for usado.
Especifique etiquetas para o componente QuickGrid na marcação Razor (<QuickGrid>...</QuickGrid>).
Indique uma fonte de dados consultável para a grelha. Use ou de uma das seguintes fontes de dados:
Items: Um IQueryable<TGridItem>anulável , onde TGridItem é o tipo de dados representado por cada linha na grade.
ItemsProvider: Um retorno de chamada que fornece dados para a grelha.
Class: Um nome de classe CSS opcional. Se fornecido, o nome da classe é incluído no atributo class da tabela renderizada.
Theme: Um nome de tema (valor padrão: default). Isso afeta quais regras de estilo correspondem à tabela.
Virtualize: Se verdadeiro, a grelha é renderizada com virtualização. Isso normalmente é usado em conjunto com a rolagem e faz com que a grelha busque e renderize apenas os dados ao redor da janela de visualização de rolagem atual. Isso pode melhorar muito o desempenho ao rolar por grandes conjuntos de dados. Se você usar Virtualize, você deve fornecer um valor para ItemSize e deve 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 paginação.
ItemSize: Aplicável apenas quando se utiliza 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 tela e garantir uma rolagem precisa.
ItemKey: Opcionalmente, define um valor para @key em cada linha renderizada. Normalmente, isso é 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, a instância @key é a TGridItem.
Pagination: Opcionalmente, vincula essa instância TGridItem a um modelo PaginationState, fazendo com que a grade busque e renderize apenas a página atual de dados. Isso normalmente é usado em conjunto com um componente Paginator ou alguma outra lógica de interface do usuário que exibe e atualiza a instância de PaginationState fornecida.
Property: Define o valor a ser exibido nas células desta coluna.
Format: Opcionalmente, especifica uma cadeia de caracteres de formato para o valor. Para usar Format, é necessário que o tipo TProp implemente IFormattable.
Sortable: Indica se os dados devem ser classificáveis por esta coluna. O valor padrão pode variar de acordo com o tipo de coluna. Por exemplo, um TemplateColumn<TGridItem> é ordenado quando qualquer parâmetro SortBy é especificado.
IsDefaultSortColumn: Indica se esta coluna deve ser classificada por padrão.
PlaceholderTemplate: Se especificado, as grades virtualizadas usam esse modelo para renderizar células cujos dados não foram carregados.
HeaderTemplate: Um modelo opcional para a célula de cabeçalho desta coluna. Se não for especificado, o modelo de cabeçalho padrão incluirá o Title, juntamente com quaisquer indicadores de classificação e botões de opções aplicáveis.
Title: Texto do título da coluna. O título é renderizado automaticamente se HeaderTemplate não for usado.
Por exemplo, adicione o seguinte componente para renderizar uma grade.
Para Blazor Web Apps, o componente QuickGrid deve adotar um modo de renderização interativo para habilitar recursos interativos, como paginação e classificação.
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();
}
Acesse o componente num navegador no caminho relativo /promotion-grid.
Atualmente, não há planos para expandir o QuickGrid com funcionalidades que as grelhas comerciais completas tendem a oferecer, como por exemplo, linhas hierárquicas, colunas que podem ser arrastadas para reordenar ou seleções de intervalo tipo Excel. Se você precisar de recursos avançados que não deseja desenvolver por conta própria, continue usando grades de terceiros.
Ordenar por coluna
O componente QuickGrid pode classificar itens por colunas. No Blazor Web Apps, a classificação requer que o componente adote um modo de renderização interativo .
No aplicativo em execução, classifique a coluna QuickGrid selecionando o título da coluna renderizada.
Itens de página com um componente Paginator
O componente QuickGrid pode paginar dados da fonte de dados. Em Blazor Web Apps, a paginação requer que o componente adote um modo de renderização interativo .
Adicione uma instância PaginationState ao bloco @code do componente. Defina o ItemsPerPage para o número de itens a serem exibidos por página. No exemplo a seguir, a instância é nomeada paginatione dez itens por página são definidos:
PaginationState pagination = new PaginationState { ItemsPerPage = 10 };
Defina a propriedade QuickGrid do componente Pagination como pagination:
<QuickGrid Items="..." Pagination="pagination">
Para fornecer uma interface do usuário para paginação, adicione um componente Paginator acima ou abaixo do componente QuickGrid. Defina o Paginator.State para pagination:
<Paginator State="pagination" />
No aplicativo em execução, percorra os itens usando um componente Paginator renderizado.
O QuickGrid renderiza linhas vazias adicionais para preencher a página final de dados quando usado com um componente Paginator. No .NET 9 ou posterior, células de dados vazias (<td></td>) são adicionadas às linhas vazias. As linhas vazias destinam-se a facilitar a renderização do QuickGrid com altura e estilo de linha estáveis em todas as páginas.
Aplicar estilos de linha
Aplique estilos a linhas usando o isolamento CSS , que pode incluir a possibilidade de estilar linhas vazias para componentes QuickGrid que dados de página com um componente Paginator.
Envolva o componente QuickGrid em um elemento de bloco de invólucro, por exemplo, um <div>:
+ <div>
<QuickGrid ...>
...
</QuickGrid>
+ </div>
Aplique um estilo de linha com o pseudo-elemento ::deep. No exemplo a seguir, a altura da linha é definida como 2em, inclusive para linhas de dados vazias.
{COMPONENT}.razor.css:
::deep tr {
height: 2em;
}
Como alternativa, use a seguinte abordagem de estilo CSS:
Exibir células de linha preenchidas com dados.
Não exiba células de linha vazias, evitando assim que as bordas dessas células sejam renderizadas pelo estilo do Bootstrap.
Use o padrão de fábrica para resolver um contexto de banco de dados EF Core que fornece dados para um componente QuickGrid. Para obter mais informações sobre por que o padrão de fábrica é recomendado, consulte ASP.NET Core Blazor com o Entity Framework Core (EF Core).
Uma fábrica de contexto de banco de dados (IDbContextFactory<TContext>) é injetada no componente com a diretiva @inject. A abordagem de fábrica requer o descarte do contexto do banco de dados, de modo que o componente implementa a interface IAsyncDisposable com a diretiva @implements. O provedor de item para o componente QuickGrid é um DbSet<T> obtido a partir do contexto de banco de dados criado (CreateDbContext) da fábrica de contexto de banco de dados injetado.
O QuickGrid reconhece instâncias de IQueryable fornecidas pelo EF e sabe como resolver consultas de forma assíncrona para obter eficiência.
O exemplo a seguir usa um ExampleTableDbSet<TEntity> (tabela) de um contexto de banco de dados AppDbContext (context) como a fonte de dados para um componente QuickGrid:
O campo context contém o contexto do banco de dados, digitado como um AppDbContext.
O método de ciclo de vida OnInitialized atribui um novo contexto de banco de dados (CreateDbContext) ao campo context da fábrica injetada (DbFactory).
O método DisposeAsync assíncrono descarta o contexto do banco de dados quando o componente é descartado.
Você também pode usar qualquer operador LINQ suportado pelo EF para filtrar os dados antes de passá-los para o parâmetro Items.
O exemplo a seguir filtra filmes por um título de filme inserido em uma caixa de pesquisa. O contexto do banco de dados é BlazorWebAppMoviesContexte o modelo é Movie. A propriedade Title do filme é utilizada na operação de filtragem.
No entanto, gerir títulos de coluna (nomes) a partir de propriedades de modelo associado geralmente é uma escolha melhor para a manutenção de uma aplicação. Um modelo pode controlar o nome de exibição de uma propriedade com o atributo [Display]. No exemplo a seguir, o modelo especifica um nome de exibição de data de lançamento do filme de "Release Date" para sua propriedade ReleaseDate:
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>().GetName() ??
memberInfo.Name;
}
base.OnParametersSet();
}
}
Utilize a subclasse no componente QuickGrid. No exemplo a seguir, o DisplayNameColumn anterior é usado. O nome "Release Date" é fornecido pelo atributo [Display] no modelo, portanto, não há necessidade de especificar uma Title:
[DisplayName("Release Date")]
public DateTime ReleaseDate { get; set; }
No entanto, o atributo [Display] é recomendado porque disponibiliza propriedades adicionais. Por exemplo, o atributo [Display] oferece a capacidade de atribuir um tipo de recurso para localização.
Dados remotos
Em aplicativos Blazor WebAssembly, buscar dados de uma API da Web baseada em JSON em um servidor é um requisito comum. Para buscar apenas os dados necessários para a página/viewport de dados atual e aplicar regras de classificação ou filtragem no servidor, use o parâmetro ItemsProvider.
ItemsProvider também pode ser usado numa aplicação Blazor no lado do servidor se a aplicação precisar consultar um ponto de extremidade externo ou noutros casos em que os requisitos não são abrangidos por um IQueryable.
Forneça um callback correspondente ao tipo de delegado GridItemsProvider<TGridItem>, onde TGridItem é o tipo de dados exibidos na grelha. O retorno de chamada recebe um parâmetro do 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 GridItemsProvider<TGridItem> converte o GridItemsProviderRequest<TGridItem> em uma consulta no banco de dados OpenFDA. Os parâmetros de consulta são convertidos para o formato de URL específico suportado pela API JSON externa. Só é possível realizar a classificação e filtragem por meio da classificação e filtragem suportadas pela API externa. O endpoint OpenFDA não suporta ordenação, portanto, nenhuma coluna está marcada como ordenável. No entanto, ele suporta ignorar registros (parâmetroskip) e limitar o retorno de registros (parâmetrolimit), para que o componente possa habilitar a virtualização e percorrer rapidamente dezenas de milhares de registros.
O QuickGrid scaffolder estrutura os componentes Razor com QuickGrid a fim de mostrar dados de uma base de dados.
A ferramenta scaffolder gera páginas básicas de Criar, Consultar, Atualizar e Remover (CRUD) com base num modelo de dados do Entity Framework Core. Você pode criar um andaime em páginas individuais ou em todas as páginas CRUD. Selecione a classe de modelo e o DbContext, criando opcionalmente um novo DbContext se necessário.
Os componentes estruturados Razor são adicionados ao projeto numa pasta gerada com o nome da classe de modelo. O componente Index gerado usa um componente QuickGrid para exibir os dados. Personalize os componentes gerados conforme necessário e habilite a interatividade para aproveitar os recursos interativos, como de paginação, de classificação e filtragem.
Os componentes produzidos pelo scaffolder requerem renderização do lado do servidor (SSR), portanto, eles não são suportados quando executados no WebAssembly.
Clique com o botão direito do mouse na pasta Components/Pages e selecione Adicionar>novo item andaime.
Com a caixa de diálogo Adicionar Novo Item de Andaime aberta para Instalada>Comum>Blazor>Razorde Componentes, selecione ComponentesRazor usando o Entity Framework (CRUD). Selecione o botão Adicionar.
CRUD é um acrônimo para Create, Read, Update e Delete. O scaffolder produz componentes de criação, edição, exclusão, detalhes e índice para o aplicativo.
Complete a caixa de diálogo Adicionar componentes Razor usando o Entity Framework (CRUD):
A lista suspensa Template inclui outros modelos para especificamente criar, editar, excluir, detalhar e listar componentes. Esta lista suspensa é útil quando se precisa apenas criar um tipo específico de componente estruturado automaticamente para uma classe de modelo. Deixe a lista suspensa Modelo definida como CRUD para montar um conjunto completo de componentes.
Na lista suspensa classe Model, selecione a classe do modelo. Uma pasta é criada para os componentes gerados a partir do nome do modelo (se a classe de modelo for nomeada Movie, a pasta será automaticamente nomeada MoviePages).
Para classe DbContext, adote uma das seguintes abordagens:
Selecione uma classe de DbContext existente que você sabe que tem um registro de provedor de fábrica (AddDbContextFactory).
Selecione o botão + (sinal de adição) e use a caixa de diálogo modal Adicionar Contexto de Dados para fornecer um novo nome de classe DbContext, registrando a classe com um fornecedor de fábrica, em vez de usar o tipo de contexto diretamente como um registo de serviço.
Depois de fechar a caixa de diálogo do modelo, a lista suspensa do provedor de banco de dados ,, passa a ter SQL Servercomo padrão. Você pode selecionar o provedor apropriado para o banco de dados que está usando. As opções incluem SQL Server, SQLite, PostgreSQL e Azure Cosmos DB.
Selecione Adicionar.
Cole todos os comandos a seguir no prompt (>) do Terminal (Terminal menu >Novo Terminal) aberto no diretório raiz do projeto. Quando você cola vários comandos, aparece um aviso informando que vários comandos serão executados. Dispense o aviso e prossiga com a operação de colagem.
Quando você cola vários comandos, todos os comandos são executados, exceto o último. O último comando não é executado até que você pressione Enter no teclado.
O comando anterior é um comando da CLI do .NET, e os comandos da CLI do .NET são executados quando inseridos num prompt do PowerShell , que é o shell de comando padrão do Terminaldo VS Code .
A tabela a seguir explica as opções do gerador de código ASP.NET Core no comando anterior.
Opção
Espaço reservado
Descrição
-dbProvider
{PROVIDER}
Provedor de banco de dados a ser usado. As opções incluem sqlserver (padrão), sqlite, cosmos, postgres.
-dc
{DB CONTEXT CLASS}
A classe DbContext a ser usada, incluindo o namespace. Para certificar-se de que uma classe DbContext está registrada nos serviços do aplicativo com um provedor de fábrica (AddDbContextFactory), use uma classe de DbContext existente que você sabe que tem um registro de provedor de fábrica ou forneça uma nova classe DbContext.
-m
{MODEL}
O nome da classe de modelo.
-outDir
{PATH}
O diretório de saída para os componentes gerados. Uma pasta é criada a partir do nome do modelo no diretório de saída para armazenar os componentes (se a classe de modelo for nomeada Movie, a pasta será automaticamente nomeada MoviePages). Normalmente, o caminho é Components/Pages para um Blazor Web App ou Pages para uma aplicação Blazor WebAssembly autónoma.
Para as opções adicionais do provedor de Blazor, use a opção de ajuda da CLI do .NET (-h|--help):
dotnet aspnet-codegenerator blazor -h
Cole todos os comandos a seguir no prompt (>) de um shell de comando aberto no diretório raiz do projeto. Quando você cola vários comandos, aparece um aviso informando que vários comandos serão executados. Dispense o aviso e prossiga com a operação de colagem.
Quando você cola vários comandos, todos os comandos são executados, exceto o último. O último comando não é executado até que você pressione Enter no teclado.
A tabela a seguir explica as opções do gerador de código ASP.NET Core no comando anterior.
Opção
Espaço reservado
Descrição
-dbProvider
{PROVIDER}
Provedor de banco de dados a ser usado. As opções incluem sqlserver (padrão), sqlite, cosmos, postgres.
-dc
{DB CONTEXT CLASS}
A classe DbContext a ser usada, incluindo o namespace. Para certificar-se de que uma classe DbContext está registrada nos serviços do aplicativo com um provedor de fábrica (AddDbContextFactory), use uma classe de DbContext existente que você sabe que tem um registro de provedor de fábrica ou forneça uma nova classe DbContext.
-m
{MODEL}
O nome da classe de modelo.
-outDir
{PATH}
O diretório de saída para os componentes gerados. Uma pasta é criada a partir do nome do modelo no diretório de saída para armazenar os componentes (se a classe de modelo for nomeada Movie, a pasta será automaticamente nomeada MoviePages). Normalmente, o caminho é Components/Pages para um Blazor Web App ou Pages para uma aplicação Blazor WebAssembly autónoma.
Para as opções adicionais do provedor de Blazor, use a opção de ajuda da CLI do .NET (-h|--help):
A origem deste conteúdo pode ser encontrada no GitHub, onde também pode criar e rever problemas e pedidos Pull. Para mais informações, consulte o nosso guia do contribuidor.
Comentários do ASP.NET Core
O ASP.NET Core é um projeto código aberto. Selecione um link para fornecer comentários:
Saiba como criar uma interface gráfica do usuário em um aplicativo Web Blazor criando e montando componentes Blazor. Aceda aos dados e partilhe-os para apresentação em várias páginas da sua aplicação.