TanStackTable v8
自动
框架
版本
菜单
入门
核心指南
功能指南
核心 API
功能 API
企业版
示例

展开指南

示例

想要直接跳到实现部分吗？请查看以下示例：

API

展开 API

展开功能指南

展开是一项功能，允许您显示和隐藏与特定行相关的其他数据行。这在您拥有分层数据并希望允许用户从更高级别深入了解数据的情况下非常有用。或者，它对于显示与行相关的其他信息也很有用。

展开功能的不同用例

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

  1. 展开子行（子行、聚合行等）
  2. 展开自定义 UI（详细信息面板、子表等）

启用客户端展开

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

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

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

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

作为展开数据的表格行

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

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

ts
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 }
    ] 
  },
]

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 数组作为展开行。表格实例现在将了解在每行上查找子行的位置。

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

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

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

自定义展开 UI

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

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

ts
//...
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>
//...

//...
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>
//...

展开行状态

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

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

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

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

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

ExpandedState 类型定义如下：

ts
type ExpandedState = true | Record<string, boolean>

type ExpandedState = true | Record<string, boolean>

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

展开行的 UI 切换处理程序

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

ts
const columns = [
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'age',
    header: 'Age',
  },
  {
    header: 'Children',
    cell: ({ row }) => {
      return row.getCanExpand() ?
        <button
          onClick={row.getToggleExpandedHandler()}
          style={{ cursor: 'pointer' }}
        >
        {row.getIsExpanded() ? '👇' : '👉'}
        </button>
       : '';
    },
  },
]

const columns = [
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'age',
    header: 'Age',
  },
  {
    header: 'Children',
    cell: ({ row }) => {
      return row.getCanExpand() ?
        <button
          onClick={row.getToggleExpandedHandler()}
          style={{ cursor: 'pointer' }}
        >
        {row.getIsExpanded() ? '👇' : '👉'}
        </button>
       : '';
    },
  },
]

筛选展开行

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

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

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

分页展开行

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

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

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

固定展开行

固定展开行的工作方式与固定常规行相同。您可以将展开行固定到表格的顶部或底部。有关行固定的更多信息，请参阅固定指南。

排序展开行

默认情况下，展开行会与表格的其余部分一起排序。

手动展开（服务器端）

如果您正在进行服务器端展开，可以通过将 manualExpanding 选项设置为 true 来启用手动行展开。这意味着 getExpandedRowModel 将不用于展开行，并且您需要在自己的数据模型中执行展开。

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

const table = useReactTable({
  // 其他选项...
  manualExpanding: true,
})
在 GitHub 上编辑
分组
分页