Guía de Filtrado Global

Ejemplos

¿Quieres ir directamente a la implementación? Consulta estos ejemplos:

• Filtros Globales

API

API de Filtrado Global

Guía de Filtrado Global

El filtrado viene en 2 modalidades: Filtrado por Columna y Filtrado Global.

Esta guía se centrará en el filtrado global, que es un filtro que se aplica a todas las columnas.

Filtrado del Lado del Cliente vs. del Lado del Servidor

Si tienes un conjunto de datos grande, es posible que no quieras cargar todos esos datos en el navegador del cliente para filtrarlos. En este caso, lo más probable es que quieras implementar filtrado, ordenación, paginación, etc. del lado del servidor.

Sin embargo, como también se discute en la Guía de Paginación, muchos desarrolladores subestiman cuántas filas se pueden cargar del lado del cliente sin afectar el rendimiento. Los ejemplos de TanStack table a menudo se prueban para manejar hasta 100,000 filas o más con un rendimiento decente para el filtrado, la ordenación, la paginación y la agrupación del lado del cliente. Esto no significa necesariamente que tu aplicación podrá manejar tantas filas, pero si tu tabla solo va a tener unos pocos miles de filas como máximo, podrías aprovechar el filtrado, la ordenación, la paginación y la agrupación del lado del cliente que TanStack table ofrece.

TanStack Table puede manejar miles de filas del lado del cliente con buen rendimiento. No descartes el filtrado, la paginación, la ordenación, etc. del lado del cliente sin antes pensarlo.

Cada caso de uso es diferente y dependerá de la complejidad de la tabla, cuántas columnas tengas, cuán grande sea cada pieza de datos, etc. Los principales cuellos de botella a los que prestar atención son:

1. ¿Puede tu servidor consultar todos los datos en un tiempo (y costo) razonable?
2. ¿Cuál es el tamaño total de la consulta? (Esto podría no escalar tan mal como piensas si no tienes muchas columnas).
3. ¿El navegador del cliente está utilizando demasiada memoria si todos los datos se cargan a la vez?

Si no estás seguro, siempre puedes empezar con el filtrado y la paginación del lado del cliente y luego cambiar a estrategias del lado del servidor en el futuro a medida que tus datos crezcan.

Filtrado Global Manual del Lado del Servidor

Si has decidido que necesitas implementar el filtrado global del lado del servidor en lugar de usar el filtrado global incorporado del lado del cliente, así es como se hace.

No se necesita la opción getFilteredRowModel de la tabla para el filtrado global manual del lado del servidor. En su lugar, los data que pasas a la tabla ya deben estar filtrados. Sin embargo, si has pasado una opción getFilteredRowModel a la tabla, puedes indicarle a la tabla que la omita configurando la opción manualFiltering en true.

const table = useReactTable({
  data,
  columns,
  // getFilteredRowModel: getFilteredRowModel(), // no es necesario para el filtrado global manual del lado del servidor
  manualFiltering: true,
});

Nota: Al usar el filtrado global manual, muchas de las opciones que se discuten en el resto de esta guía no tendrán efecto. Cuando manualFiltering se establece en true, la instancia de la tabla no aplicará ninguna lógica de filtrado global a las filas que se le pasen. En su lugar, asumirá que las filas ya están filtradas y usará los datos que le pases tal cual.

Filtrado Global del Lado del Cliente

Si estás utilizando el filtrado global incorporado del lado del cliente, primero debes pasar una función getFilteredRowModel a las opciones de la tabla.

import { useReactTable, getFilteredRowModel } from "@tanstack/react-table";
//...
const table = useReactTable({
  // otras opciones...
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(), // necesario para el filtrado global del lado del cliente
});

Función de Filtro Global

La opción globalFilterFn te permite especificar la función de filtro que se utilizará para el filtrado global. La función de filtro puede ser una cadena que hace referencia a una función de filtro incorporada, una cadena que hace referencia a una función de filtro personalizada proporcionada a través de la opción tableOptions.filterFns, o una función de filtro personalizada.

const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  globalFilterFn: "text", // función de filtro incorporada
});

Por defecto, hay 10 funciones de filtro incorporadas para elegir:

• includesString - Inclusión de cadena insensible a mayúsculas/minúsculas
• includesStringSensitive - Inclusión de cadena sensible a mayúsculas/minúsculas
• equalsString - Igualdad de cadena insensible a mayúsculas/minúsculas
• equalsStringSensitive - Igualdad de cadena sensible a mayúsculas/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 débil de objeto/referencial ==
• inNumberRange - Inclusión de rango numérico

También puedes definir tus propias funciones de filtro personalizadas como la opción de tabla globalFilterFn.

Estado del Filtro Global

El estado del filtro global se almacena en el estado interno de la tabla y se puede acceder a él a través de la propiedad table.getState().globalFilter. Si quieres persistir el estado del filtro global fuera de la tabla, puedes usar la opción onGlobalFilterChange para proporcionar una función de callback que se llamará cada vez que cambie el estado del filtro global.

const [globalFilter, setGlobalFilter] = useState < any > [];

const table = useReactTable({
  // otras opciones...
  state: {
    globalFilter,
  },
  onGlobalFilterChange: setGlobalFilter,
});

El estado de filtrado global se define como un objeto con la siguiente forma:

interface GlobalFilter {
  globalFilter: any
}

Añadir entrada de filtro global a la UI

TanStack table no añadirá una UI de entrada de filtro global a tu tabla. Debes añadirla manualmente a tu UI para permitir a los usuarios filtrar la tabla. Por ejemplo, puedes añadir una UI de entrada encima de la tabla para permitir a los usuarios introducir un término de búsqueda.

return (
  <div>
    <input
      value=""
      onChange={(e) => table.setGlobalFilter(String(e.target.value))}
      placeholder="Buscar..."
    />
  </div>
);

Función de Filtro Global Personalizada

Si quieres usar una función de filtro global personalizada, puedes definir la función y pasarla a la opción globalFilterFn.

Nota: A menudo es una idea popular usar funciones de filtrado difuso para el filtrado global. Esto se discute en la Guía de Filtrado Difuso.

const customFilterFn = (rows, columnId, filterValue) => {
  // lógica de filtro personalizada
};

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

Estado Inicial del Filtro Global

Si quieres establecer un estado de filtro global inicial cuando la tabla se inicializa, puedes pasar el estado del filtro global como parte de la opción table initialState.

Sin embargo, también puedes simplemente especificar el estado de filtro global inicial en la opción state.globalFilter.

const [globalFilter, setGlobalFilter] = useState("término de búsqueda") //recomendado inicializar el estado globalFilter aquí

const table = useReactTable({
  // otras opciones...
  initialState: {
    globalFilter: 'término de búsqueda', // si no se gestiona el estado globalFilter, establecer el estado inicial aquí
  }
  state: {
    globalFilter, // pasar nuestro estado globalFilter gestionado a la tabla
  }
})

NOTA: No uses initialState.globalFilter y state.globalFilter al mismo tiempo, ya que el estado inicializado en state.globalFilter anulará a initialState.globalFilter.

Desactivar el Filtrado Global

Por defecto, el filtrado global está habilitado para todas las columnas. Puedes desactivar el filtrado global para todas las columnas usando la opción de tabla enableGlobalFilter. También puedes desactivar tanto el filtrado por columna como el global configurando la opción de tabla enableFilters en false.

Desactivar el filtrado global hará que la API column.getCanGlobalFilter devuelva false para esa columna.

const columns = [
  {
    header: () => "Id",
    accessorKey: "id",
    enableGlobalFilter: false, // deshabilitar el filtrado global para esta columna
  },
  //...
];
//...
const table = useReactTable({
  // otras opciones...
  columns,
  enableGlobalFilter: false, // deshabilitar el filtrado global para todas las columnas
});