展开指南

展开功能指南

展开是一项功能，允许您显示和隐藏与特定行相关的额外数据行。当您拥有分层数据并希望允许用户从更高级别深入查看数据时，这会非常有用。或者，它也可以用于显示与行相关的额外信息。

展开功能的各种用例

下面将讨论 TanStack Table 中展开功能的多种用例。

展开子行（子行、聚合行等）
展开自定义 UI（详情面板、子表格等）

启用客户端展开

要使用客户端展开功能，您需要在表格选项中定义 getExpandedRowModel 函数。此函数负责返回展开的行模型。

const table = useReactTable({
  // 其他选项...
  getExpandedRowModel: getExpandedRowModel(),
})

展开的数据可以包含表格行或您想显示的任何其他数据。本指南将讨论如何处理这两种情况。

作为展开数据的表格行

展开的行本质上是子行，它们继承与其父行相同的列结构。如果您的数据对象已经包含这些展开的行数据，您可以使用 getSubRows 函数来指定这些子行。但是，如果您的数据对象不包含展开的行数据，它们可以被视为自定义展开数据，这将在下一节中讨论。

例如，如果您有以下数据对象：

type Person = {
  id: number
  name: string
  age: number
  children?: Person[] | undefined
}

const data: Person[] =  [
  { id: 1,   name: 'John',   age: 30,   children: [
      { id: 2, name: 'Jane', age: 5 },
      { id: 5, name: 'Jim', age: 10 }
    ]
   },
  { id: 3,   name: 'Doe',    age: 40,     children: [
      { id: 4, name: 'Alice', age: 10 }
    ]
   },
]

那么您可以使用 getSubRows 函数将每行中的 children 数组作为展开的行返回。表格实例现在将知道在哪里查找每行上的子行。

const table = useReactTable({
  // 其他选项...
  getSubRows: (row) => row.children, // 将 children 数组作为子行返回
  getCoreRowModel: getCoreRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})

注意：您可以有一个复杂的 getSubRows 函数，但请记住它会为每一行和每一个子行运行。如果函数未优化，这可能会很昂贵。不支持异步函数。

自定义展开 UI

在某些情况下，您可能希望显示额外的详细信息或信息，这些信息可能属于也可能不属于您的表格数据对象，例如行的展开数据。这种展开行 UI 多年来有许多名称，包括“可展开行”、“详情面板”、“子组件”等。

默认情况下，row.getCanExpand() 行实例 API 将返回 false，除非它在行上找到 subRows。这可以通过在表格实例选项中实现您自己的 getRowCanExpand 函数来覆盖。

//...
const table = useReactTable({
  // 其他选项...
  getRowCanExpand: (row) => true, // 添加您的逻辑以确定行是否可以展开。True 意味着所有行都包含展开数据
  getCoreRowModel: getCoreRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})
//...
<tbody>
  {table.getRowModel().rows.map((row) => (
    <React.Fragment key={row.id}>
     {/* 正常行 UI */}
      <tr>
        {row.getVisibleCells().map((cell) => (
          <td key={cell.id}>
            <FlexRender
              render={cell.column.columnDef.cell}
              props={cell.getContext()}
            />
          </td>
        ))}
      </tr>
      {/* 如果行已展开，则将展开的 UI 渲染为单独的行，其中包含一个跨越表格宽度的单元格 */}
      {row.getIsExpanded() && (
        <tr>
          <td colSpan={row.getAllCells().length}> // 如果展开的数据不是与父行共享相同列的行，则您希望跨越的列数
            {/* 您的自定义 UI 放在这里 */}
          </td>
        </tr>
      )}
    </React.Fragment>
  ))}
</tbody>
//...

展开行状态

如果您需要控制表格中行的展开状态，您可以通过使用 expanded 状态和 onExpandedChange 选项来实现。这允许您根据您的要求管理展开状态。

const [expanded, setExpanded] = useState<ExpandedState>({})

const table = useReactTable({
  // 其他选项...
  state: {
    expanded: expanded, // 必须将 expanded 状态传递回表格
  },
  onExpandedChange: setExpanded
})

ExpandedState 类型定义如下：

type ExpandedState = true | Record<string, boolean>

如果 ExpandedState 为 true，则表示所有行都已展开。如果它是一个记录，则只有那些 ID 作为键存在于记录中且其值设置为 true 的行才被展开。例如，如果展开状态为 { row1: true, row2: false }，则表示 ID 为 row1 的行已展开，而 ID 为 row2 的行未展开。此状态由表格用于确定哪些行已展开并应显示其 subRows（如果有）。

展开行 UI 切换处理程序

TanStack Table 不会为您的表格添加展开数据切换处理程序 UI。您应该手动将其添加到每行的 UI 中，以允许用户展开和折叠行。例如，您可以在列定义中添加一个按钮 UI。

const columns = [
  {
    accessorKey: 'name',
    header: '姓名',
  },
  {
    accessorKey: 'age',
    header: '年龄',
  },
  {
    header: '子项',
    cell: ({ row }) => {
      return row.getCanExpand() ?
        <button
          onClick={row.getToggleExpandedHandler()}
          style={{ cursor: 'pointer' }}
        >
        {row.getIsExpanded() ? '👇' : '👉'}
        </button>
       : '';
    },
  },
]

过滤展开的行

默认情况下，过滤过程从父行开始向下移动。这意味着如果父行被过滤器排除，其所有子行也将被排除。但是，您可以使用 filterFromLeafRows 选项更改此行为。当此选项启用时，过滤过程从叶（子）行开始向上移动。这确保了只要其至少一个子行或孙子行满足过滤条件，父行就会包含在过滤结果中。此外，您可以使用 maxLeafRowFilterDepth 选项控制过滤过程深入子层次结构的程度。此选项允许您指定过滤器应考虑的子行的最大深度。

//...
const table = useReactTable({
  // 其他选项...
  getSubRows: row => row.subRows,
  getCoreRowModel: getCoreRowModel(),
  getFilteredRowModel: getFilteredRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
  filterFromLeafRows: true, // 搜索展开的行
  maxLeafRowFilterDepth: 1, // 限制搜索展开行的深度
})

分页展开的行

默认情况下，展开的行与表格的其余部分一起分页（这意味着展开的行可能跨越多个页面）。如果您想禁用此行为（这意味着展开的行将始终在其父页面上渲染。这也意味着将渲染比设置的页面大小更多的行），您可以使用 paginateExpandedRows 选项。

const table = useReactTable({
  // 其他选项...
  paginateExpandedRows: false,
})

const table = useReactTable({
  // 其他选项...
  manualExpanding: true,
})

分组指南

分页指南