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

行选择指南

示例

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

API

行选择 API

行选择指南

行选择功能会跟踪哪些行被选中，并允许您以多种方式切换行的选择。让我们看一些常见的用例。

访问行选择状态

表格实例已经为您管理行选择状态（尽管如下所示，在您自己的作用域中管理行选择状态可能更方便）。您可以从一些 API 访问内部行选择状态或选定的行。

  • getState().rowSelection - 返回内部行选择状态
  • getSelectedRowModel() - 返回选定的行
  • getFilteredSelectedRowModel() - 返回筛选后选定的行
  • getGroupedSelectedRowModel() - 返回分组和排序后选定的行
ts
console.log(table.getState().rowSelection) //获取行选择状态 - { 1: true, 2: false, 等等... }
console.log(table.getSelectedRowModel().rows) //获取完整的客户端选定行
console.log(table.getFilteredSelectedRowModel().rows) //获取筛选后的客户端选定行
console.log(table.getGroupedSelectedRowModel().rows) //获取分组后的客户端选定行

console.log(table.getState().rowSelection) //获取行选择状态 - { 1: true, 2: false, 等等... }
console.log(table.getSelectedRowModel().rows) //获取完整的客户端选定行
console.log(table.getFilteredSelectedRowModel().rows) //获取筛选后的客户端选定行
console.log(table.getGroupedSelectedRowModel().rows) //获取分组后的客户端选定行

注意：如果您正在使用 manualPagination，请注意 getSelectedRowModel API 将仅返回当前页面上选定的行，因为表格行模型只能根据传入的 data 生成行。但是，行选择状态可以包含 data 数组中不存在的行 ID。

管理行选择状态

尽管表格实例已经为您管理行选择状态，但通常在您自己的作用域中管理状态会更方便，以便轻松访问选定的行 ID，您可以使用这些 ID 进行 API 调用或其他操作。

使用 onRowSelectionChange 表格选项将行选择状态提升到您自己的作用域。然后，在 state 表格选项中将行选择状态传递回表格实例。

ts
const [rowSelection, setRowSelection] = useState<RowSelectionState>({}) //管理您自己的行选择状态

const table = useReactTable({
  //...
  onRowSelectionChange: setRowSelection, //将行选择状态提升到您自己的作用域
  state: {
    rowSelection, //将行选择状态传递回表格实例
  },
})

const [rowSelection, setRowSelection] = useState<RowSelectionState>({}) //管理您自己的行选择状态

const table = useReactTable({
  //...
  onRowSelectionChange: setRowSelection, //将行选择状态提升到您自己的作用域
  state: {
    rowSelection, //将行选择状态传递回表格实例
  },
})

有用的行 ID

默认情况下，每行的行 ID 就是 row.index。如果您正在使用行选择功能，您很可能希望使用更有用的行标识符，因为行选择状态是以行 ID 为键的。您可以使用 getRowId 表格选项指定一个函数，该函数为每行返回一个唯一的行 ID。

ts
const table = useReactTable({
  //...
  getRowId: row => row.uuid, //使用数据库中行的 uuid 作为行 ID
})

const table = useReactTable({
  //...
  getRowId: row => row.uuid, //使用数据库中行的 uuid 作为行 ID
})

现在，当选择行时，行选择状态将如下所示：

json
{
  "13e79140-62a8-4f9c-b087-5da737903b76": true,
  "f3e2a5c0-5b7a-4d8a-9a5c-9c9b8a8e5f7e": false
  //...
}

{
  "13e79140-62a8-4f9c-b087-5da737903b76": true,
  "f3e2a5c0-5b7a-4d8a-9a5c-9c9b8a8e5f7e": false
  //...
}

而不是这样：

json
{
  "0": true,
  "1": false
  //...
}

{
  "0": true,
  "1": false
  //...
}

有条件地启用行选择

默认情况下，所有行都启用了行选择。要为某些行有条件地启用行选择或为所有行禁用行选择，可以使用 enableRowSelection 表格选项，该选项接受布尔值或函数以进行更精细的控制。

ts
const table = useReactTable({
  //...
  enableRowSelection: row => row.original.age > 18, //仅为成年人启用行选择
})

const table = useReactTable({
  //...
  enableRowSelection: row => row.original.age > 18, //仅为成年人启用行选择
})

要在 UI 中强制一行是否可选，可以使用 row.getCanSelect() API 来处理复选框或其他选择 UI。

单行选择

默认情况下，表格允许多行同时被选中。但是，如果您只想允许一次选择单行，可以将 enableMultiRowSelection 表格选项设置为 false 以禁用多行选择，或者传入一个函数以有条件地禁用一行的子行的多行选择。

这对于制作带有单选按钮而不是复选框的表格很有用。

ts
const table = useReactTable({
  //...
  enableMultiRowSelection: false, //一次只允许选择单行
  // enableMultiRowSelection: row => row.original.age > 18, //一次只允许为成年人选择单行
})

const table = useReactTable({
  //...
  enableMultiRowSelection: false, //一次只允许选择单行
  // enableMultiRowSelection: row => row.original.age > 18, //一次只允许为成年人选择单行
})

子行选择

默认情况下，选择父行将选择其所有子行。如果要禁用自动子行选择，可以将 enableSubRowSelection 表格选项设置为 false 以禁用子行选择，或者传入一个函数以有条件地禁用一行的子行的子行选择。

ts
const table = useReactTable({
  //...
  enableSubRowSelection: false, //禁用子行选择
  // enableSubRowSelection: row => row.original.age > 18, //禁用成年人的子行选择
})

const table = useReactTable({
  //...
  enableSubRowSelection: false, //禁用子行选择
  // enableSubRowSelection: row => row.original.age > 18, //禁用成年人的子行选择
})

渲染行选择 UI

TanStack table 不会规定您应该如何渲染行选择 UI。您可以使用复选框、单选按钮，或者只是将单击事件连接到行本身。表格实例提供了一些 API 来帮助您渲染行选择 UI。

将行选择 API 连接到复选框输入

TanStack Table 提供了一些处理函数，您可以将它们直接连接到复选框输入，以便轻松切换行选择。这些函数会自动调用其他内部 API 来更新行选择状态并重新渲染表格。

使用 row.getToggleSelectedHandler() API 连接到复选框输入以切换行的选择。

使用 table.getToggleAllRowsSelectedHandler() 或 table.getToggleAllPageRowsSelectedHandler API 连接到“全选”复选框输入以切换所有行的选择。

如果您需要对这些函数处理程序进行更精细的控制，可以直接使用 row.toggleSelected() 或 table.toggleAllRowsSelected() API。或者，您甚至可以直接调用 table.setRowSelection() API 来直接设置行选择状态，就像处理任何其他状态更新程序一样。这些处理函数只是为了方便。

tsx
const columns = [
  {
    id: 'select-col',
    header: ({ table }) => (
      <Checkbox
        checked={table.getIsAllRowsSelected()}
        indeterminate={table.getIsSomeRowsSelected()}
        onChange={table.getToggleAllRowsSelectedHandler()} //或 getToggleAllPageRowsSelectedHandler
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        onChange={row.getToggleSelectedHandler()}
      />
    ),
  },
  //... 更多列定义...
]

const columns = [
  {
    id: 'select-col',
    header: ({ table }) => (
      <Checkbox
        checked={table.getIsAllRowsSelected()}
        indeterminate={table.getIsSomeRowsSelected()}
        onChange={table.getToggleAllRowsSelectedHandler()} //或 getToggleAllPageRowsSelectedHandler
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        onChange={row.getToggleSelectedHandler()}
      />
    ),
  },
  //... 更多列定义...
]

将行选择 API 连接到 UI

如果您想要更简单的行选择 UI，只需将单击事件连接到行本身即可。row.getToggleSelectedHandler() API 也适用于此用例。

tsx
<tbody>
  {table.getRowModel().rows.map(row => {
    return (
      <tr
        key={row.id}
        className={row.getIsSelected() ? 'selected' : null}
        onClick={row.getToggleSelectedHandler()}
      >
        {row.getVisibleCells().map(cell => {
          return <td key={cell.id}>{/* */}</td>
        })}
      </tr>
    )
  })}
</tbody>

<tbody>
  {table.getRowModel().rows.map(row => {
    return (
      <tr
        key={row.id}
        className={row.getIsSelected() ? 'selected' : null}
        onClick={row.getToggleSelectedHandler()}
      >
        {row.getVisibleCells().map(cell => {
          return <td key={cell.id}>{/* */}</td>
        })}
      </tr>
    )
  })}
</tbody>
在 GitHub 上编辑
行固定
排序