Guía de estado de la tabla (React)

Ejemplos

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

Guía de estado de la tabla (React)

TanStack Table tiene un sistema de gestión de estado interno subyacente simple para almacenar y gestionar el estado de la tabla. También te permite extraer selectivamente cualquier estado que necesites gestionar en tu propio sistema de gestión de estado. Esta guía te mostrará las diferentes formas en que puedes interactuar y gestionar el estado de la tabla.

Acceso al estado de la tabla

No necesitas configurar nada especial para que el estado de la tabla funcione. Si no pasas nada a state, initialState, o a cualquiera de las opciones de la tabla on[State]Change, la tabla gestionará su propio estado internamente. Puedes acceder a cualquier parte de este estado interno utilizando la API de instancia de tabla table.getState().

const table = useReactTable({
  columns,
  data,
  //...
});

console.log(table.getState()); //accede a todo el estado interno
console.log(table.getState().rowSelection); //accede solo al estado de selección de filas

Estado inicial personalizado

Si todo lo que necesitas hacer para ciertos estados es personalizar sus valores predeterminados iniciales, aún no necesitas gestionar ninguno de los estados tú mismo. Simplemente puedes establecer valores en la opción initialState de la instancia de la tabla.

const table = useReactTable({
  columns,
  data,
  initialState: {
    columnOrder: ["age", "firstName", "lastName"], //personaliza el orden inicial de las columnas
    columnVisibility: {
      id: false, //oculta la columna id por defecto
    },
    expanded: true, //expande todas las filas por defecto
    sorting: [
      {
        id: "age",
        desc: true, //ordena por edad en orden descendente por defecto
      },
    ],
  },
  //...
});

Nota: Especifica cada estado particular solo en initialState o state, pero no en ambos. Si pasas un valor de estado particular tanto a initialState como a state, el estado inicializado en state sobrescribirá cualquier valor correspondiente en initialState.

Estado controlado

Si necesitas un acceso fácil al estado de la tabla en otras áreas de tu aplicación, TanStack Table facilita el control y la gestión de cualquier o todo el estado de la tabla en tu propio sistema de gestión de estado. Puedes hacerlo pasando tu propio estado y funciones de gestión de estado a las opciones de tabla state y on[State]Change.

Estado controlado individual

Puedes controlar solo el estado al que necesitas un acceso fácil. NO tienes que controlar todo el estado de la tabla si no lo necesitas. Se recomienda controlar solo el estado que necesitas según cada caso.

Para controlar un estado particular, necesitas pasar tanto el valor state correspondiente como la función on[State]Change a la instancia de la tabla.

Tomemos el filtrado, la ordenación y la paginación como ejemplo en un escenario de recuperación de datos "manual" del lado del servidor. Puedes almacenar el estado de filtrado, ordenación y paginación en tu propia gestión de estado, pero dejar fuera cualquier otro estado como el orden de las columnas, la visibilidad de las columnas, etc., si tu API no se preocupa por esos valores.

const [columnFilters, setColumnFilters] = React.useState([]); //sin filtros predeterminados
const [sorting, setSorting] = React.useState([
  {
    id: "age",
    desc: true, //ordena por edad en orden descendente por defecto
  },
]);
const [pagination, setPagination] = React.useState({
  pageIndex: 0,
  pageSize: 15,
});

//Usa nuestros valores de estado controlados para obtener datos
const tableQuery = useQuery({
  queryKey: ["users", columnFilters, sorting, pagination],
  queryFn: () => fetchUsers(columnFilters, sorting, pagination),
  //...
});

const table = useReactTable({
  columns,
  data: tableQuery.data,
  //...
  state: {
    columnFilters, //pasa el estado controlado de vuelta a la tabla (sobrescribe el estado interno)
    sorting,
    pagination,
  },
  onColumnFiltersChange: setColumnFilters, //eleva el estado de columnFilters a nuestra propia gestión de estado
  onSortingChange: setSorting,
  onPaginationChange: setPagination,
});
//...

Estado completamente controlado

Alternativamente, puedes controlar todo el estado de la tabla con la opción onStateChange. Esto elevará todo el estado de la tabla a tu propio sistema de gestión de estado. Ten cuidado con este enfoque, ya que podrías encontrar que elevar algunos valores de estado que cambian con frecuencia en un árbol de React, como el estado columnSizingInfo, podría causar problemas de rendimiento.

Podrían ser necesarios un par de trucos más para que esto funcione. Si usas la opción de tabla onStateChange, los valores iniciales de state deben rellenarse con todos los valores de estado relevantes para todas las características que deseas usar. Puedes escribir manualmente todos los valores de estado iniciales, o usar la API table.setOptions de una manera especial como se muestra a continuación.

//crea una instancia de tabla con valores de estado predeterminados
const table = useReactTable({
  columns,
  data,
  //... Nota: los valores de `state` AÚN NO se han pasado
});

const [state, setState] = React.useState({
  ...table.initialState, //rellena el estado inicial con todos los valores de estado predeterminados de la instancia de la tabla
  pagination: {
    pageIndex: 0,
    pageSize: 15, //opcionalmente personaliza el estado inicial de paginación.
  },
});

//Usa la API table.setOptions para fusionar nuestro estado completamente controlado en la instancia de la tabla
table.setOptions((prev) => ({
  ...prev, //conserva cualquier otra opción que hayamos configurado anteriormente
  state, //nuestro estado completamente controlado sobrescribe el estado interno
  onStateChange: setState, //cualquier cambio de estado se enviará a nuestra propia gestión de estado
}));

Callbacks de cambio de estado

Hasta ahora, hemos visto cómo las opciones de tabla on[State]Change y onStateChange funcionan para "elevar" los cambios de estado de la tabla a nuestra propia gestión de estado. Sin embargo, hay algunas cosas sobre el uso de estas opciones de las que debes ser consciente.

1. Los Callbacks de cambio de estado DEBEN tener su valor de estado correspondiente en la opción `state`.

Especificar un callback on[State]Change le indica a la instancia de la tabla que este será un estado controlado. Si no especificas el valor state correspondiente, ese estado quedará "congelado" con su valor inicial.

const [sorting, setSorting] = React.useState([]);
//...
const table = useReactTable({
  columns,
  data,
  //...
  state: {
    sorting, //requerido porque estamos usando `onSortingChange`
  },
  onSortingChange: setSorting, //hace que `state.sorting` sea controlado
});

2. Los actualizadores pueden ser valores brutos o funciones callback.

Los callbacks on[State]Change y onStateChange funcionan exactamente como las funciones setState en React. Los valores del actualizador pueden ser un nuevo valor de estado o una función callback que toma el valor de estado anterior y devuelve el nuevo valor de estado.

¿Qué implicaciones tiene esto? Significa que si quieres añadir lógica extra en cualquiera de los callbacks on[State]Change, puedes hacerlo, pero necesitas verificar si el nuevo valor del actualizador entrante es una función o un valor.

const [sorting, setSorting] = React.useState([])
const [pagination, setPagination] = React.useState({ pageIndex: 0, pageSize: 10 })

const table = useReactTable({
  columns,
  data,
  //...
  state: {
    pagination,
    sorting,
  }
  //syntax 1
  onPaginationChange: (updater) => {
    setPagination(old => {
      const newPaginationValue = updater instanceof Function ? updater(old) : updater
      //haz algo con el nuevo valor de paginación
      //...
      return newPaginationValue
    })
  },
  //syntax 2
  onSortingChange: (updater) => {
    const newSortingValue = updater instanceof Function ? updater(sorting) : updater
    //haz algo con el nuevo valor de ordenación
    //...
    setSorting(updater) //actualización de estado normal
  }
})

Tipos de estado

Todos los estados complejos en TanStack Table tienen sus propios tipos TypeScript que puedes importar y usar. Esto puede ser útil para asegurar que estás usando las estructuras de datos y propiedades correctas para los valores de estado que estás controlando.

import { useReactTable, type SortingState } from "@tanstack/react-table";
//...
const [sorting, setSorting] = React.useState<SortingState[]>([
  {
    id: "age", //deberías obtener autocompletado para las propiedades `id` y `desc`
    desc: true,
  },
]);

Ejemplos​