Skip to main content

APIs de filtrado global

Puede filtrar​

La capacidad de una columna para ser filtrada globalmente se determina por lo siguiente:

  • La columna fue definida con un accessorKey/accessorFn válido.
  • Si se proporciona, options.getColumnCanGlobalFilter devuelve true para la columna dada. Si no se proporciona, se asume que la columna es filtrable globalmente si el valor en la primera fila es de tipo string o number.
  • column.enableColumnFilter no está establecido en false
  • options.enableColumnFilters no está establecido en false
  • options.enableFilters no está establecido en false

Estado​

El estado del filtro se almacena en la tabla usando la siguiente forma:

export interface GlobalFilterTableState {
  globalFilter: any;
}

Funciones de filtro​

Puede usar las mismas funciones de filtro que están disponibles para el filtrado de columnas para el filtrado global. Consulte el Filtrado de columnas para obtener más información sobre las funciones de filtro.

Uso de las funciones de filtro​

Las funciones de filtro se pueden usar/referenciar/definir pasando lo siguiente a options.globalFilterFn:

  • Una string que referencia una función de filtro incorporada
  • Una función proporcionada directamente a la opción options.globalFilterFn

La lista final de funciones de filtro disponibles para las opciones tableOptions.globalFilterFn usa el siguiente tipo:

export type FilterFnOption<TData extends AnyData> =
  | "auto"
  | BuiltInFilterFn
  | FilterFn<TData>;

Metadatos del filtro​

El filtrado de datos a menudo puede exponer información adicional sobre los datos que se puede usar para ayudar en otras operaciones futuras sobre los mismos datos. Un buen ejemplo de este concepto es un sistema de clasificación como el de match-sorter que simultáneamente clasifica, filtra y ordena los datos. Si bien utilidades como match-sorter tienen mucho sentido para tareas de filtro+ordenación unidimensionales, la arquitectura desacoplada de filtrado/ordenación al construir una tabla las hace muy difíciles y lentas de usar.

Para que un sistema de clasificación/filtrado/ordenación funcione con tablas, las filterFn pueden opcionalmente marcar los resultados con un valor de metadato de filtro que se puede usar más tarde para ordenar/agrupar/etc. los datos a su gusto. Esto se hace llamando a la función addMeta proporcionada a su filterFn personalizado.

A continuación se muestra un ejemplo usando nuestro propio paquete match-sorter-utils (una bifurcación de utilidad de match-sorter) para clasificar, filtrar y ordenar los datos

import { sortingFns } from "@tanstack/[adapter]-table";

import { rankItem, compareItems } from "@tanstack/match-sorter-utils";

const fuzzyFilter = (row, columnId, value, addMeta) => {
  // Clasificar el elemento
  const itemRank = rankItem(row.getValue(columnId), value);

  // Almacenar la información de clasificación
  addMeta(itemRank);

  // Devolver si el elemento debe ser filtrado (dentro/fuera)
  return itemRank.passed;
};

const fuzzySort = (rowA, rowB, columnId) => {
  let dir = 0;

  // Solo ordenar por clasificación si la columna tiene información de clasificación
  if (rowA.columnFiltersMeta[columnId]) {
    dir = compareItems(
      rowA.columnFiltersMeta[columnId]!,
      rowB.columnFiltersMeta[columnId]!,
    );
  }

  // Proporcionar una alternativa alfanumérica para cuando las clasificaciones de los elementos son iguales
  return dir === 0 ? sortingFns.alphanumeric(rowA, rowB, columnId) : dir;
};

Opciones de definición de columna​

enableGlobalFilter​

enableGlobalFilter?: boolean

Habilita/deshabilita el filtro global para esta columna.

API de columna​

getCanGlobalFilter​

getCanGlobalFilter: () => boolean;

Devuelve si la columna puede ser filtrada globalmente o no. Se establece en false para deshabilitar que una columna sea escaneada durante el filtrado global.

API de fila​

columnFiltersMeta​

columnFiltersMeta: Record<string, any>;

El mapa de metadatos de los filtros de columna para la fila. Este objeto rastrea cualquier metadato de filtro para una fila según se proporcione opcionalmente durante el proceso de filtrado.

Opciones de tabla​

filterFns​

filterFns?: Record<string, FilterFn>

Esta opción le permite definir funciones de filtro personalizadas que pueden ser referenciadas en la opción filterFn de una columna por su clave. Ejemplo:

declare module "@tanstack/table-core" {
  interface FilterFns {
    myCustomFilter: FilterFn<unknown>;
  }
}

const column = columnHelper.data("key", {
  filterFn: "myCustomFilter",
});

const table = useReactTable({
  columns: [column],
  filterFns: {
    myCustomFilter: (rows, columnIds, filterValue) => {
      // devolver las filas filtradas
    },
  },
});

filterFromLeafRows​

filterFromLeafRows?: boolean

Por defecto, el filtrado se realiza desde las filas padre hacia abajo (por lo que si una fila padre es filtrada, todos sus hijos también lo serán). Establecer esta opción en true hará que el filtrado se realice desde las filas hoja hacia arriba (lo que significa que las filas padre se incluirán siempre y cuando una de sus filas hijas o nietas también esté incluida).

maxLeafRowFilterDepth​

maxLeafRowFilterDepth?: number

Por defecto, el filtrado se realiza para todas las filas (profundidad máxima de 100), sin importar si son filas padre de nivel raíz o filas hoja hijas de una fila padre. Establecer esta opción en 0 hará que el filtrado solo se aplique a las filas padre de nivel raíz, permaneciendo todas las sub-filas sin filtrar. De manera similar, establecer esta opción en 1 hará que el filtrado solo se aplique a las filas hoja hijas de 1 nivel de profundidad, y así sucesivamente.

Esto es útil para situaciones en las que desea que toda la jerarquía de hijos de una fila sea visible independientemente del filtro aplicado.

enableFilters​

enableFilters?: boolean

Habilita/deshabilita todos los filtros para la tabla.

manualFiltering​

manualFiltering?: boolean

Deshabilita el uso de getFilteredRowModel para filtrar datos. Esto puede ser útil si su tabla necesita soportar dinámicamente el filtrado tanto del lado del cliente como del lado del servidor.

getFilteredRowModel​

getFilteredRowModel?: (
  table: Table<TData>
) => () => RowModel<TData>

Si se proporciona, esta función se llama una vez por tabla y debe devolver una nueva función que calculará y devolverá el modelo de fila para la tabla cuando esta sea filtrada.

  • Para el filtrado del lado del servidor, esta función es innecesaria y puede ignorarse, ya que el servidor ya debería devolver el modelo de fila filtrado.
  • Para el filtrado del lado del cliente, esta función es obligatoria. Se proporciona una implementación predeterminada a través de la exportación { getFilteredRowModel } de cualquier adaptador de tabla.

Ejemplo:

import { getFilteredRowModel } from '@tanstack/[adapter]-table'

  getFilteredRowModel: getFilteredRowModel(),
})

globalFilterFn​

globalFilterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

La función de filtro a usar para el filtrado global.

Opciones:

onGlobalFilterChange​

onGlobalFilterChange?: OnChangeFn<GlobalFilterState>

Si se proporciona, esta función se llamará con una updaterFn cuando state.globalFilter cambie. Esto anula la gestión de estado interno predeterminada, por lo que deberá persistir el cambio de estado, ya sea total o parcialmente, fuera de la tabla.

enableGlobalFilter​

enableGlobalFilter?: boolean

Habilita/deshabilita el filtro global para la tabla.

getColumnCanGlobalFilter​

getColumnCanGlobalFilter?: (column: Column<TData>) => boolean

Si se proporciona, esta función se llamará con la columna y debería devolver true o false para indicar si esta columna debe usarse para el filtrado global. Esto es útil si la columna puede contener datos que no son string o number (es decir, undefined).

API de tabla​

getPreFilteredRowModel​

getPreFilteredRowModel: () => RowModel<TData>;

Devuelve el modelo de fila para la tabla antes de que se haya aplicado cualquier filtrado de columna.

getFilteredRowModel​

getFilteredRowModel: () => RowModel<TData>;

Devuelve el modelo de fila para la tabla después de que se haya aplicado el filtrado de columna.

setGlobalFilter​

setGlobalFilter: (updater: Updater<any>) => void

Establece o actualiza el estado state.globalFilter.

resetGlobalFilter​

resetGlobalFilter: (defaultState?: boolean) => void

Restablece el estado de globalFilter a initialState.globalFilter, o se puede pasar true para forzar un restablecimiento a un estado en blanco predeterminado (undefined).

getGlobalAutoFilterFn​

getGlobalAutoFilterFn: (columnId: string) => FilterFn<TData> | undefined;

Actualmente, esta función devuelve la función de filtro includesString incorporada. En futuras versiones, puede devolver funciones de filtro más dinámicas basadas en la naturaleza de los datos proporcionados.

getGlobalFilterFn​

getGlobalFilterFn: (columnId: string) => FilterFn<TData> | undefined;

Devuelve la función de filtro global (definida por el usuario o automática, según la configuración) para la tabla.