MainGrid

O MainGrid componente é uma grade independente para exibir registros do Dataverse. Diferente de , ele não requer um pai RecordContext — ele carrega SubGridregistros diretamente de uma tabela ou vista especificada.

Carregando por nome da tabela

Defina o TableName parâmetro para carregar automaticamente todas as visualizações públicas dessa tabela. A primeira visualização padrão é selecionada inicialmente.

Carregamento por IDs de Visualização

Use ViewIds e DefaultViewId controle exatamente quais visualizações estão disponíveis e qual é selecionada ao carregar. Você também pode fornecer CustomViewDefinitions FetchXML inline para definir views diretamente no código.

Visualizações Personalizadas com FetchXML

Use CustomViewDefinitions para definir views com consultas personalizadas em FetchXML. Isso é útil para visualizações que incluem filtros baseados no usuário atual, entidades vinculadas ou outros critérios dinâmicos.

Nota

O Id para um costume GridViewDefinition deve ser um GUID aleatório único que não corresponde a uma visualização existente do Dataverse. Se corresponder a um ID de vista existente, a visualização do Dataverse terá prioridade e a definição personalizada será ignorada.

DisplayName

Defina DisplayName em a GridViewDefinition para fornecer um rótulo padrão para a visualização no seletor suspenso sem exigir uma entrada de arquivo de localização. Se existe uma chave de localização em tables.{TableName}.views.{Id}.label, ela tem precedência sobre DisplayName. Isso é útil para visualizações personalizadas onde você quer um nome legível imediatamente, sem adicionar uma entrada de localização.

Botões da Barra de Ferramentas

Ele MainGrid suporta os mesmos botões da barra de ferramentas que SubGrido . Para grades independentes, NavigateNewRecordGridButton e NavigateOpenRecordGridButton são comumente usados para navegar até páginas de formulário separadas. Consulte a documentação dos Botões da Grade para uma referência completa de todos os botões disponíveis e suas opções de configuração.

Comportamento na Caixa de Busca

Quando o usuário digita na caixa de busca da grade, a visualização configurada é automaticamente reconsultada com condições adicionais de filtro aplicadas a cada coluna elegível para busca mostrada na visualização. As condições são unidas à OR lógica, de modo que um registro é incluído se alguma de suas colunas visíveis corresponder ao termo de busca. A semântica padrão de correspondência varia dependendo do tipo de coluna.

Colunas de Texto e Pesquisa

Colunas de texto (campos de string) e colunas de consulta (comparadas com o nome principal do registro alvo) usam por padrão um início com busca. A digitação joh corresponde a valores que começam com joh — por exemplo John , ou Johnson. A correspondência é delegada ao operador do like FetchXML, que é insensível a maiúsculas minúsculas no Dataverse.

Use * como coringa para um emparelhamento mais flexível. Digitar *hn executa uma correspondência no estilo contains (por exemplo, John), Johnsondigitação j*n corresponde a valores onde quaisquer caracteres podem aparecer entre o j e o n (por exemplo, John). Joneson O coringa é convertido para o coringa do % FetchXML no momento da consulta.

Colunas de Escolha

Colunas de escolha (conjuntos de opções / listas de seleção) e colunas de seleção múltipla são comparadas com o rótulo de exibição localizado de cada opção, em vez do valor inteiro subjacente. Rótulos são comparados de forma insensível a maiúsculas e minúsculas e acentuadas na cultura do usuário atual, então digitar cafe corresponderá a uma opção rotulada Café. Quando um ou mais rótulos de opção coincidem, a consulta emite uma condição FetchXML contra os valores correspondentes — uma in condição para colunas de escolha de seleção única, ou contain-values uma condição para colunas de escolha de múltiplas seleções. Quando nenhuma etiqueta corresponde, a coluna não contribui com nenhuma condição (mantendo o OR filtro compacto).

Colunas de escolha honram o mesmo * coringa que as colunas de texto: por padrão, a correspondência começa com (digitando act correspondências Active), e um início * muda para contains (digitando *act correspondências Inactiveadicionais). As linhas correspondentes têm a substring correspondente destacada na grade, exatamente como as correspondências de coluna de texto.

Colunas Numérica e Monetária

Colunas numéricas — int, big int, decimal, double e money — suportam operadores de comparação no termo de busca. A caixa de busca analisa um operador inicial opcional e aplica o correspondente operador de condição FetchXML:

• = 100 ou apenas 100  —  igual (o padrão quando nenhum operador é especificado)
• > 100  —  maior que
• < 100  —  menos que
• >= 100  —  maior que igual ou maior que
• <= 100  —  menor que ou igual

Nota

As condições de busca para cada tipo de coluna são adicionadas ao mesmo OR grupo de filtros, de modo que o mesmo termo de busca é avaliado simultaneamente contra colunas de texto, colunas de pesquisa, colunas de escolha e colunas numéricas. Digitar 100 uma grade que tenha tanto uma coluna de nome quanto uma coluna de valor irá corresponder a registros cujo nome começa com 100 ou cujo valor é igual a 100. O filtro de busca é sobreposto ao filtro existente da visualização, então as restrições em nível de visualização (como um statecode = 0 filtro) são sempre preservadas.

Desativando a busca

Configurado AllowSearch="false" na grade para esconder completamente a caixa de busca. Isso é útil para grades que contêm apenas um pequeno conjunto fixo de registros, ou onde o filtragem é gerenciada externamente (por exemplo, via uma barra de ferramentas personalizada).

Modo de paginação

A grade suporta duas estratégias de paginação via o PagingMode parâmetro (Blazor) / pagingMode prop (React). Ambos os modos usam a mesma visualização subjacente, FetchXML, ordenação e busca — apenas a forma como as linhas são reveladas ao usuário difere.

• Paged (padrão) — um rodapé clássico Pré-Anterior/Próximo com seletor de página. Ideal para conjuntos de resultados mais curtos e para casos em que o usuário quer pular por número de página ou compartilhar uma página com links profundos na URL.
• Virtualize — pergaminho infinito. O rodapé do pager fica oculto, as linhas se acumulam à medida que o usuário passa pela parte inferior renderizada, e a próxima página é buscada automaticamente. Um contador somente leitura "Mostrando 1-N de M" substitui o pager assim que o total estiver disponível. Ideal para listas longas onde o usuário escaneia em vez de navegar por página.

Opte definindo o modo de paginação na grade:

Concessões

• Nada de ir direto para a página. O modo virtualização sempre começa na primeira página e avança; os consumidores não podem mais pular para a página N. Se você precisa de navegação explícita na página, fique em Paged.
• A página não é mantida. Como a posição de rolagem do usuário não é um conceito de página discreta, PersistedStateQueryParameter a chave é p omitida no modo virtualizar. A busca selecionada para visualizar, ordenar e (opt-in) ainda percorreu a URL.
• Busca e ordenação ainda funcionam, mas eles resetam o acumulador rolado — mudar a visualização ativa, aplicar uma nova ordenação ou digitar na caixa de busca elimina as linhas carregadas e rebusca do topo.
• Oculta o pager / seletor de tamanho de página. O seletor de tamanho de página é substituído por um tamanho fixo de bloco; defina o valor inicial via DefaultItemsPerPage (Blazor) / pageSize (React) para controlar quantas linhas são buscadas por página ativada pelo rolamento.

Modo de Tamanho Completo

Definido FullSize="true" para fazer a grade expandir e preencher toda a altura do seu recipiente pai. Isso é útil quando a grade é o conteúdo principal de uma página.

Estado persistente da grade

Definido PersistedStateQueryParameter para um nome de parâmetro de consulta (por exemplo, "gridState") e a grade refletirá seu estado interativo em um único parâmetro de URL sob esse nome. Cada alteração conduzida pelo usuário — trocar a visualização selecionada, paginar, redimensionar o tamanho da página, clicar em cabeçalhos de coluna para ordenar ou digitar (opt-in) digitar na caixa de busca — recodifica o estado e substitui o parâmetro URL no lugar. Quando a página é aberta com o parâmetro presente (favorito, link compartilhado, atualização), a grade lê o parâmetro na primeira carga e restaura todo o estado capturado antes de buscar os dados.

O que Persiste

O parâmetro de consulta codifica um objeto JSON compacto com uma chave curta por pedaço de estado. As chaves são propositalmente abreviadas para manter URLs favoritas curtas. Campos que correspondem aos seus padrões naturais são omitidos, então uma grade na página 1 sem ordenação e sem busca produz uma mancha muito menor do que uma com todos os cinco campos preenchidos.

• v — o GUID da vista selecionada (minúscula, hifenizada, sem aparelhos). Corresponde a uma das ViewIds / CustomViewDefinitions entradas com as quais a grade foi configurada.
• p — o número de página baseado em 1. Omitido quando o usuário está na página 1 (o padrão).
• ps — o número de linhas por página. Reflete a última seleção do usuário no menu suspenso do tamanho da página; omitido quando corresponde à grade DefaultItemsPerPage.
• s — um conjunto ordenado de diretivas de ordenação. Cada entrada tem c (nome lógico da coluna) e uma opcional d (definida para true decrescente; ascendente é o padrão não marcado, então d é omitida nesse caso). O estado vazio / não ordenado omite completamente o campo. A ordenação multi-coluna é preservada em ordem de precedência.
• q — o texto atual da caixa de busca. Só incluído quando a grade foi configurada com IncludeSearchInPersistedState="true" E a caixa tem um valor não vazio. Está desregulado por padrão, já que os termos de busca podem ser sensíveis (por exemplo, nomes de clientes em um contexto de CRM).

Codificação de URL

O estado é serializado como JSON compacto (sem espaço em branco) e codificado por URL no parâmetro de consulta. Uma grade mostrando a página 3 de uma visualização de contato, ordenada por sobrenome, ascendente e depois criada descendente, com a busca "smith" ativada, faria a seguinte carga útil de ida e volta:

Após a codificação de URLs, o valor real da barra de endereços fica assim (o framework chama encodeURIComponent a string JSON antes de escrevê-la):

Strip por valor padrão

O codificador remove qualquer campo que corresponda ao seu padrão natural antes da serialização. A página 1 descarta p, uma lista de ordenação vazia cai s, uma ordenação ascendente não marcada cai d, e uma busca vazia descarta q. Uma grade recém-carregada, sem interação do usuário, codifica para um blob contendo apenas v e ps — impedindo que URLs favoritos cresçam para o estado que o consumidor não tocou.

Comportamento do Histórico do Navegador

Mudanças de estado atualizam a URL com history.replaceState — elas não enviam novas entradas para a pilha traseira. Isso significa que ao clicar Voltar de uma página de grade, retorna à página distinta anterior (a origem de navegação do usuário), e não à combinação de ordenação/página anterior. A troca é intencional: uma única sessão de grade pode gerar dezenas de mudanças de estado, e pressionar cada uma como uma entrada de navegação tornaria o botão Voltar praticamente inútil no restante do app.

Ativando a persistência da busca

Por padrão, o texto de busca é excluído da URL, então o parâmetro é seguro para compartilhamento mesmo quando a grade está filtrando por um termo sensível. Definido IncludeSearchInPersistedState="true" para incluir o valor atual da caixa de busca na carga útil codificada (adicionado como o q campo acima). Uma vez ativada, a busca passa a fazer parte do estado de marcador — o usuário pode copiar a URL e o destinatário fica na mesma combinação de visualização, página, ordenação E filtro.

Compatibilidade entre stacks

A forma JSON codificada é idêntica entre as implementações de Blazor e React grid — mesmo nome de parâmetro, mesmas chaves (v / p / ps / s / ), qmesma semântica de valores. Um link produzido por uma pilha é consumível pela outra, então uma organização que executa ambas as superfícies (por exemplo, um portal público do React junto com um app interno de administração do Blazor) pode compartilhar URLs de grade entre elas sem qualquer camada de tradução por pilha.

Múltiplas grades em uma página

Duas grades na mesma página devem usar nomes diferentesPersistedStateQueryParameter. Cada grade apenas lê e escreve seu próprio parâmetro, então reutilizar o mesmo nome faria com que ambas as grades disputassem o mesmo slot de URL — a última gravação vence e a outra grade perde seu estado a cada alteração. Uma convenção típica é nomear o parâmetro com base no papel da grade (por exemplo, contactsState + accountsState).

Grades Multi-Tabela

A MainGrid pode exibir visualizações de diferentes tabelas incluindo IDs de visualização de múltiplas tabelas na ViewIds coleção. Quando o usuário troca de vista, a grade carrega automaticamente os dados da tabela correta. Use o OnClick callback nos botões de navegação para definir dinamicamente a URL com base no nome da tabela da visualização selecionada.