Guía de Columnas

API

API de Tabla

Guía de Definiciones de Columna

Las definiciones de columna (column defs) son la parte más importante en la construcción de una tabla. Son responsables de:

• Construir el modelo de datos subyacente que se utilizará para todo, incluyendo la clasificación, el filtrado, el agrupamiento, etc.
• Formatear el modelo de datos para lo que se mostrará en la tabla
• Crear grupos de encabezado, encabezados y pies de página
• Crear columnas con fines de solo visualización, por ejemplo, botones de acción, casillas de verificación, expansores, minigráficos, etc.

Tipos de Definiciones de Columna

Los siguientes "tipos" de definiciones de columna (column defs) no son realmente tipos de TypeScript, sino más bien una forma de hablar y describir categorías generales de definiciones de columna:

• Accessor Columns
  • Las columnas de acceso tienen un modelo de datos subyacente, lo que significa que pueden ser clasificadas, filtradas, agrupadas, etc.
• Display Columns
  • Las columnas de visualización no tienen un modelo de datos, lo que significa que no pueden ser clasificadas, filtradas, etc., pero pueden ser usadas para mostrar contenido arbitrario en la tabla, por ejemplo, un botón de acciones de fila, una casilla de verificación, un expansor, etc.
• Grouping Columns
  • Las columnas de agrupación no tienen un modelo de datos, por lo que tampoco pueden ser clasificadas, filtradas, etc., y se utilizan para agrupar otras columnas. Es común definir un encabezado o pie de página para un grupo de columnas.

Ayudantes de Columna

Aunque las definiciones de columna (column defs) son simplemente objetos al final del día, una función createColumnHelper se expone desde el núcleo de la tabla que, cuando se llama con un tipo de fila, devuelve una utilidad para crear diferentes tipos de definición de columna con la mayor seguridad de tipo posible.

Aquí hay un ejemplo de cómo crear y usar un ayudante de columna:

// Define la forma de tu fila
type Person = {
  firstName: string;
  lastName: string;
  age: number;
  visits: number;
  status: string;
  progress: number;
};

const columnHelper = createColumnHelper<Person>();

// ¡Crea algunas columnas!
const defaultColumns = [
  // Columna de Visualización
  columnHelper.display({
    id: "actions",
    cell: (props) => <RowActions row={props.row} />,
  }),
  // Columna de Agrupación
  columnHelper.group({
    header: "Nombre",
    footer: (props) => props.column.id,
    columns: [
      // Columna de Acceso
      columnHelper.accessor("firstName", {
        cell: (info) => info.getValue(),
        footer: (props) => props.column.id,
      }),
      // Columna de Acceso
      columnHelper.accessor((row) => row.lastName, {
        id: "lastName",
        cell: (info) => info.getValue(),
        header: () => <span>Apellido</span>,
        footer: (props) => props.column.id,
      }),
    ],
  }),
  // Columna de Agrupación
  columnHelper.group({
    header: "Información",
    footer: (props) => props.column.id,
    columns: [
      // Columna de Acceso
      columnHelper.accessor("age", {
        header: () => "Edad",
        footer: (props) => props.column.id,
      }),
      // Columna de Agrupación
      columnHelper.group({
        header: "Más Información",
        columns: [
          // Columna de Acceso
          columnHelper.accessor("visits", {
            header: () => <span>Visitas</span>,
            footer: (props) => props.column.id,
          }),
          // Columna de Acceso
          columnHelper.accessor("status", {
            header: "Estado",
            footer: (props) => props.column.id,
          }),
          // Columna de Acceso
          columnHelper.accessor("progress", {
            header: "Progreso del Perfil",
            footer: (props) => props.column.id,
          }),
        ],
      }),
    ],
  }),
];

Creando Columnas de Acceso

Las columnas de datos son únicas en el sentido de que deben configurarse para extraer valores primitivos para cada elemento en tu array data.

Hay 3 formas de hacer esto:

• Si tus elementos son objects, usa una clave de objeto que corresponda al valor que quieres extraer.
• Si tus elementos son arrays anidados, usa un índice de array que corresponda al valor que quieres extraer.
• Usa una función de acceso (accessor function) que devuelva el valor que quieres extraer.

Claves de Objeto

Si cada uno de tus elementos es un objeto con la siguiente forma:

type Person = {
  firstName: string;
  lastName: string;
  age: number;
  visits: number;
  status: string;
  progress: number;
};

Podrías extraer el valor de firstName de la siguiente manera:

columnHelper.accessor('firstName')

// OR

{
  accessorKey: 'firstName',
}

Índices de Array

Si cada uno de tus elementos es un array con la siguiente forma:

type Sales = [Date, number];

Podrías extraer el valor number de la siguiente manera:

columnHelper.accessor(1)

// OR

{
  accessorKey: 1,
}

Funciones de Acceso

Si cada uno de tus elementos es un objeto con la siguiente forma:

type Person = {
  firstName: string;
  lastName: string;
  age: number;
  visits: number;
  status: string;
  progress: number;
};

Podrías extraer un valor de nombre completo calculado de la siguiente manera:

columnHelper.accessor(row => `${row.firstName} ${row.lastName}`, {
  id: 'fullName',
})

// OR

{
  id: 'fullName',
  accessorFn: row => `${row.firstName} ${row.lastName}`,
}

🧠 Recuerda, el valor accedido es lo que se utiliza para ordenar, filtrar, etc., por lo que querrás asegurarte de que tu función de acceso devuelva un valor primitivo que pueda ser manipulado de manera significativa. Si devuelves un valor no primitivo como un objeto o un array, necesitarás las funciones apropiadas de filtro/ordenación/agrupación para manipularlos, ¡o incluso proporcionar las tuyas propias! 😬

IDs de Columna Únicos

Las columnas se identifican de forma única con 3 estrategias:

• Si se define una columna de acceso con una clave de objeto o un índice de array, se utilizará lo mismo para identificar la columna de forma única.
  • Cualquier punto (.) en una clave de objeto será reemplazado por guiones bajos (_).
• Si se define una columna de acceso con una función de acceso
  • La propiedad id de la columna se utilizará para identificar la columna de forma única O
  • Si se proporciona un encabezado string primitivo, esa cadena de encabezado se utilizará para identificar la columna de forma única

🧠 Una forma fácil de recordar: Si defines una columna con una función de acceso, proporciona un encabezado de cadena o una propiedad id única.

Formato y Renderizado de Columnas

Por defecto, las celdas de las columnas mostrarán el valor de su modelo de datos como una cadena. Puedes anular este comportamiento proporcionando implementaciones de renderizado personalizadas. Cada implementación recibe información relevante sobre la celda, el encabezado o el pie de página y devuelve algo que tu adaptador de framework puede renderizar, por ejemplo, JSX/Componentes/cadenas/etc. Esto dependerá del adaptador que estés utilizando.

Hay un par de formateadores disponibles:

• cell: Se utiliza para formatear celdas.
• aggregatedCell: Se utiliza para formatear celdas cuando están agregadas.
• header: Se utiliza para formatear encabezados.
• footer: Se utiliza para formatear pies de página.

Formato de Celda

Puedes proporcionar un formateador de celda personalizado pasando una función a la propiedad cell y usando la función props.getValue() para acceder al valor de tu celda:

columnHelper.accessor("firstName", {
  cell: (props) => <span>{props.getValue().toUpperCase()}</span>,
});

Los formateadores de celda también reciben los objetos row y table, lo que te permite personalizar el formato de la celda más allá del valor de la misma. El siguiente ejemplo proporciona firstName como el acceso, pero también muestra un ID de usuario prefijado que se encuentra en el objeto de fila original:

columnHelper.accessor("firstName", {
  cell: (props) => (
    <span>{`${props.row.original.id} - ${props.getValue()}`}</span>
  ),
});

Formato de Celda Agregada

Para más información sobre celdas agregadas, consulta agrupación.

Formato de Encabezado y Pie de Página

Los encabezados y pies de página no tienen acceso a los datos de la fila, pero aún utilizan los mismos conceptos para mostrar contenido personalizado.