Skip to main content

APIs de Filtrado de Columnas

Puede Filtrar​

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

  • La columna se definió con un accessorKey/accessorFn válido.
  • column.enableColumnFilter no está configurado como false
  • options.enableColumnFilters no está configurado como false
  • options.enableFilters no está configurado como false

Estado​

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

export interface ColumnFiltersTableState {
  columnFilters: ColumnFiltersState;
}

export type ColumnFiltersState = ColumnFilter[];

export interface ColumnFilter {
  id: string;
  value: unknown;
}

Funciones de Filtro​

Las siguientes funciones de filtro están integradas en el núcleo de la tabla:

  • includesString
    • Inclusión de cadena sin distinción entre mayúsculas y minúsculas
  • includesStringSensitive
    • Inclusión de cadena con distinción entre mayúsculas y minúsculas
  • equalsString
    • Igualdad de cadena sin distinción entre mayúsculas y minúsculas
  • equalsStringSensitive
    • Igualdad de cadena con distinción entre mayúsculas y minúsculas
  • arrIncludes
    • Inclusión de elemento dentro de un array
  • arrIncludesAll
    • Todos los elementos incluidos en un array
  • arrIncludesSome
    • Algunos elementos incluidos en un array
  • equals
    • Igualdad de objeto/referencial Object.is/===
  • weakEquals
    • Igualdad de objeto/referencial débil ==
  • inNumberRange
    • Inclusión en rango numérico

Cada función de filtro recibe:

  • La fila a filtrar
  • El columnId a usar para recuperar el valor de la fila
  • El valor del filtro

y debería devolver true si la fila debe incluirse en las filas filtradas, y false si debe eliminarse.

Esta es la firma de tipo para cada función de filtro:

export type FilterFn<TData extends AnyData> = {
  (
    row: Row<TData>,
    columnId: string,
    filterValue: any,
    addMeta: (meta: any) => void,
  ): boolean;
  resolveFilterValue?: TransformFilterValueFn<TData>;
  autoRemove?: ColumnFilterAutoRemoveTestFn<TData>;
  addMeta?: (meta?: any) => void;
};

export type TransformFilterValueFn<TData extends AnyData> = (
  value: any,
  column?: Column<TData>,
) => unknown;

export type ColumnFilterAutoRemoveTestFn<TData extends AnyData> = (
  value: any,
  column?: Column<TData>,
) => boolean;

export type CustomFilterFns<TData extends AnyData> = Record<
  string,
  FilterFn<TData>
>;

filterFn.resolveFilterValue​

Este método opcional "colgante" en cualquier filterFn permite que la función de filtro transforme/sanee/formatee el valor del filtro antes de que se pase a la función de filtro.

filterFn.autoRemove​

Este método opcional "colgante" en cualquier filterFn recibe un valor de filtro y se espera que devuelva true si el valor del filtro debe eliminarse del estado del filtro. Por ejemplo, algunos filtros de estilo booleano pueden querer eliminar el valor del filtro del estado de la tabla si el valor del filtro se establece en false.

Uso de las Funciones de Filtro​

Las funciones de filtro pueden usarse/referenciarse/definirse pasando lo siguiente a columnDefinition.filterFn:

  • Una string que hace referencia a una función de filtro integrada
  • Una función proporcionada directamente a la opción columnDefinition.filterFn

La lista final de funciones de filtro disponibles para la opción columnDef.filterFn usa el siguiente tipo:

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

Meta del Filtro​

El filtrado de datos a menudo puede exponer información adicional sobre los datos que se puede utilizar para ayudar a 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 datos. Si bien las utilidades como match-sorter tienen mucho sentido para tareas de filtro+ordenación unidimensionales, la arquitectura de filtrado/ordenación desacoplada de la construcción de 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 filterFns pueden, opcionalmente, marcar los resultados con un valor filter meta que puede usarse más tarde para ordenar/agrupar/etc. los datos a tu gusto. Esto se hace llamando a la función addMeta proporcionada a tu filterFn personalizado.

A continuación se muestra un ejemplo utilizando 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/react-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 (incluido/excluido)
  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 un respaldo alfanumérico para cuando las clasificaciones de los elementos sean iguales
  return dir === 0 ? sortingFns.alphanumeric(rowA, rowB, columnId) : dir;
};

Opciones de Definición de Columna​

filterFn​

filterFn?: FilterFn | keyof FilterFns | keyof BuiltInFilterFns

La función de filtro a usar con esta columna.

Opciones:

enableColumnFilter​

enableColumnFilter?: boolean

Habilita/deshabilita el filtro de columna para esta columna.

API de Columna​

getCanFilter​

getCanFilter: () => boolean;

Devuelve si la columna puede o no ser filtrada por columna.

getFilterIndex​

getFilterIndex: () => number;

Devuelve el índice (incluyendo -1) del filtro de columna en el array state.columnFilters de la tabla.

getIsFiltered​

getIsFiltered: () => boolean;

Devuelve si la columna está actualmente filtrada o no.

getFilterValue​

getFilterValue: () => unknown;

Devuelve el valor de filtro actual de la columna.

setFilterValue​

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

Una función que establece el valor de filtro actual para la columna. Puedes pasarle un valor o una función updater para operaciones seguras de inmutabilidad sobre valores existentes.

getAutoFilterFn​

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

Devuelve una función de filtro calculada automáticamente para la columna basándose en el primer valor conocido de la columna.

getFilterFn​

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

Devuelve la función de filtro (ya sea definida por el usuario o automática, dependiendo de la configuración) para el columnId especificado.

API de Fila​

columnFilters​

columnFilters: Record<string, boolean>;

El mapa de filtros de columna para la fila. Este objeto rastrea si una fila pasa/falla filtros específicos por su ID de columna.

columnFiltersMeta​

columnFiltersMeta: Record<string, any>;

El mapa de metadatos de 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 te 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/[adapter]-table" {
  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 (es decir, si una fila padre se filtra, todos sus hijos también se filtrarán). Configurar esta opción como true hará que el filtrado se realice desde las filas hoja hacia arriba (lo que significa que las filas padre se incluirán siempre que 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 las filas hoja hijas de una fila padre. Configurar esta opción en 0 hará que el filtrado se aplique solo a las filas padre de nivel raíz, quedando todas las subfilas sin filtrar. De manera similar, configurar esta opción en 1 hará que el filtrado se aplique solo a las filas hoja hijas de 1 nivel de profundidad, y así sucesivamente.

Esto es útil para situaciones en las que deseas 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 tu tabla necesita soportar dinámicamente tanto el filtrado del lado del cliente como del lado del servidor.

onColumnFiltersChange​

onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>

Si se proporciona, esta función será llamada con un updaterFn cuando state.columnFilters cambie. Esto anula la gestión de estado interna predeterminada, por lo que deberás persistir el cambio de estado de forma total o parcial fuera de la tabla.

enableColumnFilters​

enableColumnFilters?: boolean

Habilita/deshabilita todos los filtros de columna para la tabla.

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 se filtre.

  • 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(),
})

API de Tabla​

setColumnFilters​

setColumnFilters: (updater: Updater<ColumnFiltersState>) => void

Establece o actualiza el estado state.columnFilters.

resetColumnFilters​

resetColumnFilters: (defaultState?: boolean) => void

Restablece el estado de columnFilters a initialState.columnFilters, o se puede pasar true para forzar un restablecimiento a un estado en blanco predeterminado [].

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.