Todos los componentes (244)

Constructor de consultas

Gestión · QueryBuilder

Qué es y cuándo usarlo

Un constructor de consultas con grupos anidados: condiciones «campo, operador, valor» unidas por «y» o por «o», con grupos dentro de grupos y la posibilidad de negar un grupo.

Cuándo usarlo

Un filtro que no cabe en un par de desplegables: «importe mayor de 100 y (cliente empieza por Ac o no cobrada)».
fields son los campos, cada uno con su tipo (text, number, date o boolean): el tipo decide los operadores y el campo de valor.
Entrega un árbol de datos (QueryGroup) por onChange. Para aplicarlo en el cliente, filterByQuery(registros, consulta, campos, leer); en el servidor se recorre el mismo árbol.
value lo hace controlado; sin él, empieza en initialValue. maxDepth limita cuántos grupos caben uno dentro de otro (5 como máximo).
Una condición a medias (sin valor) no filtra nada, así que se puede ir montando sin vaciar la lista.

Cuándo no

Un filtro simple de una tabla: el panel de filtros avanzados de Table, que usa la misma lógica de condiciones.
Búsqueda por texto libre: un campo de búsqueda.
El árbol no se valida contra el servidor: quien lo recibe decide qué campos y operadores acepta.

Teclado: es un conjunto de controles normales; el tabulador recorre cada grupo en orden, y cada cambio de estructura (añadir o quitar) se anuncia.

Accesibilidad: cada grupo es un grupo con nombre («Grupo 2»); cada condición numera sus campos («Valor de la condición 3»). La negación y el «y/o» son controles con etiqueta, no solo color: la raya del grupo cambia, pero también lo dice su casilla.

Aspecto fino: cada grupo es una caja con una raya a la izquierda del color de acento, o del de error si está negado; las condiciones se parten en varias líneas cuando no caben.

Cómo se ve

Se cumple

Negar el grupo

Campo de la condición 1
Cliente
Estado
Total (€)
Operador de la condición 1
contiene
no contiene
es igual a
es distinto de
empieza por
está vacío
no está vacío
Valor de la condición 1
Pagado
Pendiente
Enviado
Campo de la condición 2
Cliente
Estado
Total (€)
Operador de la condición 2
es igual a
es distinto de
mayor que
mayor o igual que
menor que
menor o igual que
entre
está vacío
no está vacío
Valor de la condición 2

2 condiciones activas

Ver la consulta como

LOWER("estado") = ? AND "total" > ?
-- parámetros: ["pagado",100]

1 de 5 pedidos cumplen la consulta.

<QueryBuilder
  label="Qué pedidos buscar"
  fields={campos}
  value={consulta}
  onChange={setConsulta}
  summary
  exports={["sql", "text"]}
/>

Props

Se importa con import { QueryBuilder } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`fields`obligatoria	`readonly QueryField[]`	Los campos por los que se puede filtrar, con su tipo: el tipo decide los operadores y el campo de valor.
`label`obligatoria	`string`	Que consulta es («Filtro de facturas»): nombra el constructor para quien usa un lector de pantalla. Obligatorio.
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`disabled`	`boolean`	—
`exports`	`readonly QueryExportFormat[]`	Debajo del constructor, la consulta escrita en estos formatos (uno cada vez, elegido de una lista): `sql` (un `WHERE` con sus parametros), `mongo` (un filtro) y `text` (una frase). El mismo texto sale de `queryToSql`, `queryToMongo` y `queryToText`, para usar la consulta en el servidor. Por defecto, no se enseña.
`initialValue`	`QueryGroup`	—
`maxDepth`	`number`	Cuantos grupos se pueden meter uno dentro de otro, contando el raiz. Por defecto, 5, que es tambien el tope.
`onChange`	`(value: QueryGroup) => void`	—
`readOnly`	`boolean`	Se ve y se recorre, pero no cambia.
`summary`	`boolean`	El recuento de condiciones activas bajo el constructor. Por defecto, si.
`value`	`QueryGroup`	La consulta. Si se pasa, el constructor es controlado.

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: