表头指南

表头 API

本快速指南将讨论在 TanStack Table 中检索和操作 header 对象（表头对象）的不同方法。

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

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

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

<thead>
  {table.getHeaderGroups().map(headerGroup => {
    return (
      <tr key={headerGroup.id}>
        {headerGroup.headers.map(header => ( // map over the headerGroup headers array
          <th key={header.id} colSpan={header.colSpan}>
            {/* */}
          </th>
        ))}
      </tr>
    )
  })}
</thead>

<thead>
  {table.getHeaderGroups().map(headerGroup => {
    return (
      <tr key={headerGroup.id}>
        {headerGroup.headers.map(header => ( // map over the headerGroup headers array
          <th key={header.id} colSpan={header.colSpan}>
            {/* */}
          </th>
        ))}
      </tr>
    )
  })}
</thead>

有多个 table 实例 API 可用于检索表头列表，具体取决于您使用的功能。您最常使用的 API 可能是 table.getFlatHeaders，它将返回表格中所有表头的扁平列表。但还有至少十几个其他表头在列可见性和列固定功能方面很有用。根据您的用例，像 table.getLeftLeafHeaders 或 table.getRightFlatHeaders 这样的 API 可能很有用。

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

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

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

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

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

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

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

表头还附带了一些其他有用的 API，用于与表格状态进行交互。其中大多数与列大小调整和调整功能相关。有关更多信息，请参阅 列大小调整指南。

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

{headerGroup.headers.map(header => (
  <th key={header.id} colSpan={header.colSpan}>
    {/* Handles all possible header column def scenarios for `header` */}
    {flexRender(header.column.columnDef.header, header.getContext())}
  </th>
))}

{headerGroup.headers.map(header => (
  <th key={header.id} colSpan={header.colSpan}>
    {/* Handles all possible header column def scenarios for `header` */}
    {flexRender(header.column.columnDef.header, header.getContext())}
  </th>
))}