Guía de la Instancia de Tabla

API

Guía de la Instancia de Tabla

TanStack Table es una biblioteca de UI sin interfaz. Cuando hablamos de la table o "instancia de tabla", no nos referimos a un elemento <table> literal. En cambio, nos referimos al objeto central de la tabla que contiene el estado y las APIs de la tabla. La instancia de table se crea llamando a la función createTable de su adaptador (p. ej. useReactTable, createSolidTable, createSvelteTable, useQwikTable, useVueTable).

Creación de una Instancia de Tabla

Para crear una instancia de tabla, se requieren 2 options: columns y data. Hay docenas de otras opciones de tabla para configurar características y comportamiento, pero estas 2 son obligatorias.

Definición de Datos

data es un array de objetos que se convertirán en las filas de su tabla. Cada objeto en el array representa una fila de datos (en circunstancias normales). Si está utilizando TypeScript, generalmente definimos un tipo para la forma de nuestros datos. Este tipo se utiliza como un tipo genérico para todas las demás instancias de tabla, columna, fila y celda. A este tipo se le suele denominar TData.

Por ejemplo, si tenemos una tabla que muestra una lista de usuarios en un array como este:

[
  {
    "firstName": "Tanner",
    "lastName": "Linsley",
    "age": 33,
    "visits": 100,
    "progress": 50,
    "status": "Married"
  },
  {
    "firstName": "Kevin",
    "lastName": "Vandy",
    "age": 27,
    "visits": 200,
    "progress": 100,
    "status": "Single"
  }
]

Entonces podemos definir un tipo User (TData) como este:

//TData
type User = {
  firstName: string;
  lastName: string;
  age: number;
  visits: number;
  progress: number;
  status: string;
};

Luego podemos definir nuestro array data con este tipo, y entonces TanStack Table podrá inferir inteligentemente muchos tipos para nosotros más adelante en nuestras columnas, filas, celdas, etc.

//nota: data necesita una referencia "estable" para evitar re-renderizados infinitos
const data: User[] = [];
//or
const [data, setData] = React.useState<User[]>([]);
//or
const data = ref<User[]>([]);
//etc...

Nota: data necesita una referencia "estable" (especialmente en React) para evitar re-renderizados infinitos. Por esta razón, recomendamos usar React.useState o React.useMemo, o definir sus datos fuera del mismo componente de React que crea la instancia de tabla, o usar una biblioteca como TanStack Query para gestionar el estado de sus datos.

Definición de Columnas

Las definiciones de columnas se tratan en detalle en la siguiente sección en la Guía de Definición de Columnas. Sin embargo, aquí señalaremos que cuando defina el tipo de sus columnas, debe usar el mismo tipo TData que usó para sus datos.

const columns: ColumnDef<User>[] = []; //Pasar el tipo User como el tipo genérico TData
//or
const columnHelper = createColumnHelper<User>(); //Pasar el tipo User como el tipo genérico TData

Las definiciones de columnas son donde le diremos a TanStack Table cómo cada columna debe acceder y/o transformar los datos de la fila con un accessorKey o un accessorFn. Consulte la Guía de Definición de Columnas para más información.

Creación de la Instancia de Tabla

Con nuestras columns y data definidas, ahora podemos crear nuestra instancia básica de tabla.

//vanilla js
const table = createTable({ columns, data });

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

//solid
const table = createSolidTable({ columns, data });

//svelte
const table = createSvelteTable({ columns, data });

//vue
const table = useVueTable({ columns, data });

Entonces, ¿qué hay en la instancia de table? Echemos un vistazo a las interacciones que podemos tener con la instancia de tabla.

Estado de la Tabla

La instancia de tabla contiene todo el estado de la tabla, al que se puede acceder a través de la API table.getState(). Cada característica de la tabla registra varios estados en el estado de la tabla. Por ejemplo, la característica de selección de filas registra el estado rowSelection, la característica de paginación registra el estado pagination, etc.

Cada característica también tendrá APIs de configuración de estado (state setter APIs) y APIs de reinicio de estado (state resetter APIs) correspondientes en la instancia de tabla. Por ejemplo, la característica de selección de filas tendrá una API setRowSelection y una resetRowSelection.

table.getState().rowSelection; //leer el estado de selección de filas
table.setRowSelection((old) => ({ ...old })); //establecer el estado de selección de filas
table.resetRowSelection(); //restablecer el estado de selección de filas

APIs de la Tabla

Hay docenas de APIs de tabla creadas por cada característica para ayudarle a leer o mutar el estado de la tabla de diferentes maneras.

La documentación de referencia de la API para la instancia de tabla central y todas las demás APIs de características se puede encontrar en toda la documentación de la API.

Por ejemplo, puede encontrar la documentación de la API de la instancia de tabla central aquí: API de la Tabla

Modelos de Fila de la Tabla

Existe un conjunto especial de APIs de instancia de tabla para leer filas de la instancia de tabla llamadas modelos de fila. TanStack Table tiene características avanzadas donde las filas que se generan pueden ser muy diferentes del array de data que pasó originalmente. Para obtener más información sobre los diferentes modelos de fila que puede pasar como una opción de tabla, consulte la Guía de Modelos de Fila.

API​