表头指南

这份快速指南将讨论如何检索和与 TanStack Table 中的表头对象 (header objects) 进行交互。

表头相当于单元格，但用于表格的 <thead> 部分，而不是 <tbody> 部分。

从何处获取表头

表头来自表头组 (Header Groups)，表头组相当于行，但用于表格的 <thead> 部分，而不是 <tbody> 部分。

表头组的表头 (HeaderGroup Headers)

如果你在一个表头组中，表头作为数组存储在 headerGroup.headers 属性中。通常你只需遍历此数组来渲染你的表头。

<thead>
  {table.getHeaderGroups().map(headerGroup => {
    return (
      <tr key={headerGroup.id}>
        {headerGroup.headers.map(header => ( // 遍历 headerGroup.headers 数组
          <th key={header.id} colSpan={header.colSpan}>
            {/* */}
          </th>
        ))}
      </tr>
    )
  })}
</thead>

表头表格实例 API (Header Table Instance APIs)

有多个表格实例 API 可用于根据你使用的功能检索表头列表。你可能最常使用的 API 是 table.getFlatHeaders，它将返回表格中所有表头的扁平列表，但还有至少十几个其他表头在与列可见性和列固定功能结合使用时很有用。例如，table.getLeftLeafHeaders 或 table.getRightFlatHeaders 可能根据你的用例有所帮助。

表头对象 (Header Objects)

表头对象与单元格对象 (Cell objects) 类似，但用于表格的 <thead> 部分，而不是 <tbody> 部分。每个表头对象都可以与你 UI 中的 <th> 或类似的单元格元素关联。表头对象上有一些属性和方法，你可以使用它们来与表格状态交互，并根据表格的状态从表格中提取单元格值。

表头 ID (Header IDs)

每个表头对象都有一个 id 属性，使其在表格实例中独一无二。通常，你只需要此 id 作为 React 键的唯一标识符，或者如果你遵循高性能列调整大小示例。

对于没有高级嵌套或分组表头逻辑的简单表头，header.id 将与其父 column.id 相同。但是，如果表头是组列的一部分或占位符单元格，它将具有一个更复杂的 ID，该 ID 由表头族、深度/表头行索引、列 ID 和表头组 ID 构成。

嵌套分组表头属性 (Nested Grouped Headers Properties)

表头对象上有一些属性只有当表头是嵌套或分组表头结构的一部分时才有用。这些属性包括：

colSpan: 表头应该跨越的列数。这对于在 <th> 元素上渲染 colSpan 属性很有用。
rowSpan: 表头应该跨越的行数。这对于在 <th> 元素上渲染 rowSpan 属性很有用。（目前在默认 TanStack Table 中尚未实现）
depth: 表头组所属的表头组“行索引”。
isPlaceholder: 一个布尔标志，如果表头是占位符表头 (placeholder header)，则为 true。占位符表头用于在列被隐藏或列是组列的一部分时填补空白。
placeholderId: 占位符表头的唯一标识符。
subHeaders: 属于此表头的子/子表头数组。如果表头是叶表头，则为空。

注意： header.index 指的是它在表头组（表头行）中的索引，即它从左到右的位置。它与 header.depth 不同，header.depth 指的是表头组“行索引”。

表头父对象 (Header Parent Objects)

每个表头都存储对其父列对象 (column object) 及其父表头组对象 (header group object) 的引用。

表头渲染 (Header Rendering)

由于你定义的 header 列选项可以是字符串、JSX 或返回其中之一的函数，所以渲染表头的最佳方式是使用适配器中的 flexRender 工具，它将为你处理所有这些情况。

{headerGroup.headers.map(header => (
  <th key={header.id} colSpan={header.colSpan}>
    {/* 处理所有可能的 `header` 列定义场景 */}
    {flexRender(header.column.columnDef.header, header.getContext())}
  </th>
))}

表头组指南

列指南