MainGrid

El MainGrid componente es una cuadrícula independiente para mostrar registros de Dataverse. A diferencia de SubGrid, no requiere un padre RecordContext — carga registros directamente desde una tabla o vista especificada.

Carga por nombre de tabla

Configura el TableName parámetro para que cargue automáticamente todas las vistas públicas de esa tabla. La primera vista predeterminada se selecciona inicialmente.

Carga por identificadores de vista

Usar ViewIds y DefaultViewId controlar exactamente qué vistas están disponibles y cuál se selecciona al cargar. También puedes proporcionar CustomViewDefinitions FetchXML en línea para definir vistas directamente en código.

Vistas personalizadas con FetchXML

Úsalo CustomViewDefinitions para definir vistas con consultas personalizadas de FetchXML. Esto es útil para vistas que incluyen filtros basados en el usuario actual, entidades vinculadas u otros criterios dinámicos.

Nota

El Id para una costumbre GridViewDefinition debe ser un GUID aleatorio único que no corresponda a una vista existente de Dataverse. Si coincide con un ID de vista existente, la vista Dataverse tendrá prioridad y la definición personalizada será ignorada.

DisplayName

Configura DisplayName en a GridViewDefinition para proporcionar una etiqueta predeterminada para la vista en el selector desplegable sin requerir una entrada de archivo de localización. Si existe una clave de localización en tables.{TableName}.views.{Id}.label, tiene precedencia sobre DisplayName. Esto es útil para vistas personalizadas donde quieres un nombre legible de inmediato sin añadir una entrada de localización.

Botones de la barra de herramientas

Soporta MainGrid los mismos botones de la barra de herramientas que SubGrid. Para cuadrículas independientes, NavigateNewRecordGridButton y NavigateOpenRecordGridButton se usan comúnmente para navegar a páginas de formulario separadas. Consulta la documentación de Grid Buttons para una referencia completa de todos los botones disponibles y sus opciones de configuración.

Comportamiento en la caja de búsqueda

Cuando el usuario escribe en el cuadro de búsqueda de la cuadrícula, la vista configurada se vuelve a consultar automáticamente con condiciones de filtro adicionales aplicadas a cada columna elegible para búsqueda mostrada en la vista. Las condiciones se unen con OR lógica, por lo que se incluye un registro si alguna de sus columnas visibles coincide con el término de búsqueda. La semántica de coincidencia por defecto varía según el tipo de columna.

Columnas de texto y consulta

Las columnas de texto (campos de cadena) y las columnas de búsqueda (comparadas con el nombre principal del registro objetivo) usan por defecto un inicio de búsqueda . La tipificación joh coincide con valores que comienzan con joh — por ejemplo John o Johnson. La coincidencia se delega al operador de like FetchXML, que es insensible a mayúsculas y minúsculas en Dataverse.

Úsalo * como comodín para un emparejamiento más flexible. Al escribir *hn , se realiza una coincidencia al estilo contains-(por ejemplo, John), Johnsonla tipificación j*n coincide con valores donde pueden aparecer caracteres entre el j y ( n por ejemplo, John, Joneson). El comodín se convierte en comodín de % FetchXML en el momento de la consulta.

Columnas de elección

Las columnas de elección (conjuntos de opciones / listas de selección) y las columnas de selección múltiple se comparan con la etiqueta de visualización localizada de cada opción en lugar del valor entero subyacente. Las etiquetas se comparan de forma insensible a mayúsculas y minúsculas y acentual en la cultura del usuario actual, por lo que escribir cafe coincidirá con una opción etiquetada Café. Cuando una o más etiquetas de opción coinciden, la consulta emite una condición FetchXML contra los valores de opción coincidentes — una in condición para columnas de selección única, o contain-values una condición para columnas de selección múltiple. Cuando ninguna etiqueta coincide, la columna no aporta ninguna condición (manteniendo el OR filtro compacto).

Las columnas de elección respetan el mismo * comodín que las columnas de texto: por defecto la coincidencia comienza con (escribiendo act coincidencias Active), y una salida * cambia a contains (escribiendo *act coincidencias Inactiveadicionales ). Las filas coincidentes tienen la subcadena correspondiente resaltada en la cuadrícula, exactamente como las coincidencias de columnas de texto.

Columnas numéricas y de dinero

Las columnas numéricas — int, int grande, decimal, double y money — permiten operadores de comparación en el término de búsqueda. El cuadro de búsqueda analiza un operador inicial opcional y aplica el correspondiente operador de condición FetchXML:

• = 100 o simplemente 100  —  igual (el valor por defecto cuando no se especifica ningún operador)
• > 100  —  mayor que
• < 100  —  menos que
• >= 100  —  mayor o igual
• <= 100  —  menor o igual

Nota

Las condiciones de búsqueda para cada tipo de columna se añaden al mismo OR grupo de filtros, de modo que el mismo término de búsqueda se evalúa simultáneamente frente a columnas de texto, columnas de búsqueda, columnas de elección y columnas numéricas. Escribir 100 una cuadrícula que tenga tanto una columna de nombre como una columna de cantidad coincidirá con registros cuyo nombre empiece por 100 o cuyo importe sea igual a 100. El filtro de búsqueda se superpone al filtro existente de la vista, por lo que las restricciones a nivel de vista (como un statecode = 0 filtro) siempre se conservan.

Desactivar la búsqueda

Configurado AllowSearch="false" en la cuadrícula para ocultar completamente el cuadro de búsqueda. Esto es útil para cuadrículas que contienen solo un pequeño conjunto fijo de registros, o donde el filtrado se gestiona externamente (por ejemplo, a través de una barra de herramientas personalizada).

Modo de paginación

La cuadrícula soporta dos estrategias de paginación mediante el PagingMode parámetro (Blazor) / pagingMode prop (React). Ambos modos utilizan la misma vista subyacente, FetchXML, ordenación y búsqueda — solo que la forma en que se muestran las filas al usuario difiere.

• Paged (por defecto) — un clásico pie de página Anterior / Siguiente con un selector de tamaño de página. Es ideal para conjuntos de resultados más cortos y para casos en los que el usuario quiera saltar por número de página o compartir una página enlazada en profundidad en la URL.
• Virtualize — pergamino infinito. El pie de página del buscapersonas queda oculto, las filas se acumulan a medida que el usuario pasa por la parte inferior renderizada, y la siguiente página se recupera automáticamente. Un contador de solo lectura "Mostrando 1-N de M" reemplaza al buscapersonas una vez que hay disponible el total. Es ideal para listas largas donde el usuario escanea en lugar de navegar por página.

Opta por participar configurando el modo de paginación en la cuadrícula:

Compensaciones

• No hay salto a la página. El modo virtualización siempre comienza en la primera página y avanza; los consumidores ya no pueden saltar a la página N. Si necesitas una navegación explícita por la página, mantente en Paged.
• No se mantiene la página. Como la posición de desplazamiento del usuario no es un concepto de página discreto, PersistedStateQueryParameter se omite la p clave en modo virtualización. Vista seleccionada, ordenación y búsqueda (opt-in) siguen recorriendo la URL.
• Buscar y ordenar siguen funcionando, pero reinician el acumulador desplazado — cambiar la vista activa, aplicar un nuevo ordenamiento o escribir en el cuadro de búsqueda elimina las filas cargadas y vuelve a buscar desde arriba.
• Oculta el buscapersonas / selector de tamaño de página. El selector de tamaño de página se sustituye por un tamaño de bloque fijo; establecer el valor inicial mediante DefaultItemsPerPage (Blazor) / pageSize (React) para controlar cuántas filas se obtienen por cada página activada por desplazamiento.

Modo de tamaño completo

Configurado FullSize="true" para que la cuadrícula se expanda y llene toda la altura de su contenedor principal. Esto es útil cuando la cuadrícula es el contenido principal de una página.

Estado de la cuadrícula persistente

Se establece PersistedStateQueryParameter en un nombre de parámetro de consulta (por ejemplo, "gridState") y la cuadrícula reflejará su estado interactivo en un único parámetro de URL bajo ese nombre. Cada cambio impulsado por el usuario — cambiar la vista seleccionada, paginar, redimensionar el tamaño de la página, hacer clic en cabeceras de columna para ordenar o (optar por suscripción) escribir en el cuadro de búsqueda — vuelve a codificar el estado y reemplaza el parámetro URL en su lugar. Cuando la página se abre con el parámetro presente (marcador, enlace compartido, actualización), la cuadrícula lee el parámetro en la primera carga y restaura todo el estado capturado antes de obtener los datos.

Lo que se mantiene

El parámetro de consulta codifica un objeto JSON compacto con una tecla corta por cada pieza de estado. Las claves se abrevian deliberadamente para mantener las URLs marcadas cortas. Se omiten los campos que coinciden con sus valores naturales por defecto, por lo que una cuadrícula en la página 1 sin orden ni búsqueda produce un blob mucho más pequeño que uno con los cinco campos poblados.

• v — el GUID de la vista seleccionada (minúscula, guionado, sin brackets). Coincide con una de las ViewIds entradas / CustomViewDefinitions con las que se configuró la cuadrícula.
• p — el número de página basado en 1. Se omite cuando el usuario está en la página 1 (por defecto).
• ps — el número de filas por página. Refleja la última selección del usuario en el desplegable de tamaño de página; se omite cuando coincide con la de la DefaultItemsPerPagecuadrícula.
• s — una orden ordenada de directivas de ordenación. Cada entrada tiene c (nombre lógico de columna) y una opción d (establecida como true para descendente; ascendente es el valor por defecto no marcado, por lo que d se omite en ese caso). El estado vacío / sin ordenar omite el campo por completo. La ordenación multicolumna se conserva en orden de precedencia.
• q — el texto actual de la caja de búsqueda. Solo se incluye cuando la cuadrícula está configurada con IncludeSearchInPersistedState="true" Y la caja tiene un valor no vacío. Desactivado por defecto, ya que los términos de búsqueda pueden ser sensibles (por ejemplo, nombres de clientes en un contexto CRM).

Codificación de URL

El estado se serializa como JSON compacto (sin espacio en blanco) y se codifica URL en el parámetro de consulta. Una cuadrícula que mostraba la página 3 de una vista de contacto, ordenada por apellido, ascendiendo y creada al descender, con la búsqueda "smith" activada, enviaba la siguiente carga útil:

Después de la codificación de URLs, el valor real de la barra de direcciones se ve así (el framework llama encodeURIComponent a la cadena JSON antes de escribirla):

Desmontaje por valor predeterminado

El codificador elimina cualquier campo que coincida con su predeterminado natural antes de serializar. La página 1 cae p, una lista de ordenación vacía cae s, una ordenación ascendente sin marcar cae d, y una búsqueda vacía deja q. Una cuadrícula recién cargada sin interacción del usuario codifica en un blob que contiene solo v y ps — impidiendo que las URLs marcadas crezcan para un estado que el consumidor no ha tocado.

Comportamiento del historial de navegador

Los cambios de estado actualizan la URL con history.replaceState — no envían nuevas entradas a la pila trasera. Esto significa que pulsar Atrás desde una página de cuadrícula vuelve a la página distinta anterior (el origen de navegación del usuario), no a la combinación de ordenación/página anterior. El compromiso es intencionado: una sola sesión de cuadrícula puede producir decenas de cambios de estado, y pulsar cada uno como entrada de navegación haría que el botón Atrás fuera prácticamente inútil en el resto de la aplicación.

Activando la persistencia de búsqueda

Por defecto, el texto de búsqueda se excluye de la URL, por lo que el parámetro es seguro para compartir incluso cuando la cuadrícula filtra por un término sensible. Configura IncludeSearchInPersistedState="true" para incluir el valor actual del cuadro de búsqueda en la carga útil codificada (añadido como el q campo anterior). Una vez habilitada, la búsqueda pasa a formar parte del estado de marcador — el usuario puede copiar la URL y el destinatario aparece en la misma combinación de vista, página, ordenación Y filtro.

Compatibilidad entre pilas

La forma JSON codificada es idéntica entre las implementaciones de Blazor y React Grid: mismo nombre de parámetro, mismas claves (v / p / ps / s / ), qmisma semántica de valores. Un enlace producido por una pila es consumible por la otra, por lo que una organización que ejecuta ambas superficies (por ejemplo, un portal público de React junto con una aplicación interna de administración de Blazor) puede compartir URLs de cuadrícula entre ellas sin ninguna capa de traducción por pila.

Múltiples cuadrículas en una sola página

Dos cuadrículas en la misma página deben usar nombres diferentesPersistedStateQueryParameter. Cada cuadrícula solo lee y escribe su propio parámetro, por lo que reutilizar el mismo nombre haría que ambas cuadrículas compitieran por la misma ranura de URL: gana la última escritura y la otra cuadrícula pierde su estado en cada cambio. Una convención típica es nombrar el parámetro según el rol de la cuadrícula (por ejemplo, contactsState + accountsState).

Rejillas Multi-Tabla

A MainGrid puede mostrar vistas de diferentes tablas incluyendo identificadores de vista de varias tablas de la ViewIds colección. Cuando el usuario cambia de vista, la cuadrícula carga automáticamente los datos de la tabla correcta. Utiliza el OnClick callback en los botones de navegación para establecer dinámicamente la URL según el nombre de la tabla de la vista seleccionada.