Guía de Encabezados

API

Guía de Encabezados

Esta guía rápida discutirá las diferentes formas en que puedes recuperar e interactuar con objetos header en TanStack Table.

Los encabezados son el equivalente de las celdas, pero están destinados a la sección <thead> de la tabla en lugar de la sección <tbody>.

Dónde Obtener Encabezados

Los encabezados provienen de Grupos de Encabezados, que son el equivalente de las filas, pero están destinados a la sección <thead> de la tabla en lugar de la sección <tbody>.

Encabezados de HeaderGroup

Si estás en un grupo de encabezados, los encabezados se almacenan como un array en la propiedad headerGroup.headers. Normalmente, simplemente iterarás sobre este array para renderizar tus encabezados.

<thead>
  {table.getHeaderGroups().map((headerGroup) => {
    return (
      <tr key={headerGroup.id}>
        {headerGroup.headers.map(
          (
            header, // itera sobre el array de encabezados de headerGroup
          ) => (
            <th key={header.id} colSpan={header.colSpan}>
              {/* */}
            </th>
          ),
        )}
      </tr>
    );
  })}
</thead>

APIs de Instancia de Tabla de Encabezados

Hay múltiples APIs de instancia table que puedes usar para recuperar una lista de encabezados dependiendo de las características que estés utilizando. La API más común que podrías usar es table.getFlatHeaders, que devolverá una lista plana de todos los encabezados en la tabla, pero hay al menos una docena de otros encabezados que son útiles en conjunto con las características de visibilidad de columna y fijación de columna. APIs como table.getLeftLeafHeaders o table.getRightFlatHeaders podrían ser útiles dependiendo de tu caso de uso.

Objetos de Encabezado

Los objetos de encabezado son similares a los objetos de Celda, pero están destinados a la sección <thead> de la tabla en lugar de la sección <tbody>. Cada objeto de encabezado puede asociarse con un <th> o elemento de celda similar en tu interfaz de usuario. Hay algunas propiedades y métodos en los objetos header que puedes usar para interactuar con el estado de la tabla y extraer valores de celda de la tabla basándose en el estado de la tabla.

IDs de Encabezado

Cada objeto de encabezado tiene una propiedad id que lo hace único dentro de la instancia de la tabla. Normalmente, solo necesitas este id como un identificador único para las claves de React o si estás siguiendo el ejemplo de redimensionamiento de columna de alto rendimiento.

Para encabezados simples sin lógica avanzada de encabezados anidados o agrupados, el header.id será el mismo que su padre column.id. Sin embargo, si el encabezado es parte de una columna de grupo o una celda de marcador de posición, tendrá un ID más complicado que se construye a partir de la familia del encabezado, el índice de profundidad/fila del encabezado, el ID de columna y el ID del grupo de encabezados.

Propiedades de Encabezados Agrupados Anidados

Hay algunas propiedades en los objetos header que solo son útiles si el encabezado forma parte de una estructura de encabezados anidados o agrupados. Estas propiedades incluyen:

colspan: El número de columnas que el encabezado debe abarcar. Esto es útil para renderizar el atributo colSpan en el elemento <th>.
rowSpan: El número de filas que el encabezado debe abarcar. Esto es útil para renderizar el atributo rowSpan en el elemento <th>. (Actualmente no implementado en TanStack Table por defecto)
depth: El "índice de fila" del grupo de encabezados al que pertenece el grupo de encabezados.
isPlaceholder: Un indicador booleano que es verdadero si el encabezado es un encabezado de marcador de posición. Los encabezados de marcador de posición se utilizan para llenar los huecos cuando una columna está oculta o cuando una columna forma parte de una columna de grupo.
placeholderId: El identificador único para el encabezado de marcador de posición.
subHeaders: El array de sub-encabezados/encabezados hijos que pertenecen a este encabezado. Estará vacío si el encabezado es un encabezado hoja.

Nota: header.index se refiere a su índice dentro del grupo de encabezados (fila de encabezados), es decir, su posición de izquierda a derecha. No es lo mismo que header.depth, que se refiere al "índice de fila" del grupo de encabezados.

Objetos Padre de Encabezado

Cada encabezado almacena una referencia a su objeto padre columna y a su objeto padre grupo de encabezados.

Más APIs de Encabezados

Los encabezados tienen algunas APIs más útiles adjuntas a ellos que son útiles para interactuar con el estado de la tabla. La mayoría de ellas se relacionan con las características de tamaño y redimensionamiento de columnas. Consulta la Guía de Redimensionamiento de Columnas para más información.

Renderizado de Encabezados

Dado que la opción de columna header que definiste puede ser una cadena, jsx o una función que devuelva cualquiera de ellos, la mejor manera de renderizar los encabezados es usar la utilidad flexRender de tu adaptador, la cual manejará todos esos casos por ti.

{
  headerGroup.headers.map((header) => (
    <th key={header.id} colSpan={header.colSpan}>
      {/* Maneja todos los posibles escenarios de definición de columna de encabezado para `header` */}
      {flexRender(header.column.columnDef.header, header.getContext())}
    </th>
  ));
}

API​