Guía de Agrupación

Ejemplos

¿Quieres saltar a la implementación? Echa un vistazo a estos ejemplos:

• grouping

API

API de Agrupación

Guía de Agrupación

Hay 3 características de tabla que pueden reordenar las columnas, las cuales ocurren en el siguiente orden:

1. Fijación de Columnas - Si se fijan, las columnas se dividen en columnas fijadas a la izquierda, al centro (sin fijar) y a la derecha.
2. Ordenación Manual de Columnas - Se aplica un orden de columnas especificado manualmente.
3. Agrupación - Si la agrupación está habilitada, un estado de agrupación está activo, y tableOptions.groupedColumnMode está configurado a 'reorder' | 'remove', entonces las columnas agrupadas se reordenan al inicio del flujo de columnas.

La agrupación en TanStack table es una característica que se aplica a las columnas y te permite categorizar y organizar las filas de la tabla basándose en columnas específicas. Esto puede ser útil en casos donde tienes una gran cantidad de datos y deseas agruparlos según ciertos criterios.

Para usar la característica de agrupación, necesitarás usar el modelo de filas agrupadas. Este modelo es responsable de agrupar las filas basándose en el estado de agrupación.

import { getGroupedRowModel } from "@tanstack/react-table";

const table = useReactTable({
  // otras opciones...
  getGroupedRowModel: getGroupedRowModel(),
});

Cuando el estado de agrupación está activo, la tabla añadirá las filas coincidentes como subRows a la fila agrupada. La fila agrupada se añadirá a las filas de la tabla en el mismo índice que la primera fila coincidente. Las filas coincidentes se eliminarán de las filas de la tabla. Para permitir al usuario expandir y contraer las filas agrupadas, puedes usar la característica de expansión.

import { getGroupedRowModel, getExpandedRowModel } from "@tanstack/react-table";

const table = useReactTable({
  // otras opciones...
  getGroupedRowModel: getGroupedRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
});

Estado de agrupación

El estado de agrupación es un array de strings, donde cada string es el ID de una columna por la cual agrupar. El orden de los strings en el array determina el orden de la agrupación. Por ejemplo, si el estado de agrupación es ['column1', 'column2'], entonces la tabla agrupará primero por column1, y luego dentro de cada grupo, agrupará por column2. Puedes controlar el estado de agrupación usando la función setGrouping:

table.setGrouping(["column1", "column2"]);

También puedes restablecer el estado de agrupación a su estado inicial usando la función resetGrouping:

table.resetGrouping();

Por defecto, cuando una columna es agrupada, se mueve al inicio de la tabla. Puedes controlar este comportamiento usando la opción groupedColumnMode. Si la configuras a 'reorder', entonces las columnas agrupadas se moverán al inicio de la tabla. Si la configuras a 'remove', entonces las columnas agrupadas se eliminarán de la tabla. Si la configuras a false, entonces las columnas agrupadas no se moverán ni se eliminarán.

const table = useReactTable({
  // otras opciones...
  groupedColumnMode: "reorder",
});

Agregaciones

Cuando las filas están agrupadas, puedes agregar los datos en las filas agrupadas por columnas usando la opción aggregationFn. Este es un string que es el ID de la función de agregación. Puedes definir las funciones de agregación usando la opción aggregationFns.

const column = columnHelper.accessor("key", {
  aggregationFn: "sum",
});

En el ejemplo anterior, la función de agregación 'sum' se usará para agregar los datos en las filas agrupadas. Por defecto, las columnas numéricas usarán la función de agregación 'sum', y las columnas no numéricas usarán la función de agregación 'count'. Puedes anular este comportamiento especificando la opción aggregationFn en la definición de la columna.

Hay varias funciones de agregación integradas que puedes usar:

• sum - Suma los valores en las filas agrupadas.
• count - Cuenta el número de filas en las filas agrupadas.
• min - Encuentra el valor mínimo en las filas agrupadas.
• max - Encuentra el valor máximo en las filas agrupadas.
• extent - Encuentra el rango (mínimo y máximo) de los valores en las filas agrupadas.
• mean - Encuentra la media de los valores en las filas agrupadas.
• median - Encuentra la mediana de los valores en las filas agrupadas.
• unique - Devuelve un array de valores únicos en las filas agrupadas.
• uniqueCount - Cuenta el número de valores únicos en las filas agrupadas.

Agregaciones Personalizadas

Cuando las filas están agrupadas, puedes agregar los datos en las filas agrupadas usando la opción aggregationFns. Este es un registro donde las claves son los IDs de las funciones de agregación, y los valores son las propias funciones de agregación. Luego puedes referenciar estas funciones de agregación en la opción aggregationFn de una columna.

const table = useReactTable({
  // otras opciones...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // devuelve el valor agregado
    },
  },
});

En el ejemplo anterior, myCustomAggregation es una función de agregación personalizada que toma el ID de la columna, las filas hoja y las filas hijas, y devuelve el valor agregado. Luego puedes usar esta función de agregación en la opción aggregationFn de una columna:

const column = columnHelper.accessor("key", {
  aggregationFn: "myCustomAggregation",
});

Agrupación Manual

Si estás realizando una agrupación y agregación del lado del servidor, puedes habilitar la agrupación manual usando la opción manualGrouping. Cuando esta opción se establece en true, la tabla no agrupará automáticamente las filas usando getGroupedRowModel() y, en su lugar, esperará que agrupes manualmente las filas antes de pasarlas a la tabla.

const table = useReactTable({
  // otras opciones...
  manualGrouping: true,
});

Nota: Actualmente no hay muchas maneras fáciles conocidas de realizar una agrupación del lado del servidor con TanStack Table. Necesitarás hacer mucha renderización de celdas personalizada para que esto funcione.

Manejador de Cambio de Agrupación

Si quieres gestionar el estado de agrupación tú mismo, puedes usar la opción onGroupingChange. Esta opción es una función que se llama cuando el estado de agrupación cambia. Puedes pasar el estado gestionado de vuelta a la tabla a través de la opción tableOptions.state.grouping.

const [grouping, setGrouping] = useState<string[]>([]);

const table = useReactTable({
  // otras opciones...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping,
});