行选择指南

示例

想跳过直接看实现？请查看这些示例：

React 行选择
Vue 行选择
React 展开

行选择指南

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

访问行选择状态

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

getState().rowSelection - 返回内部行选择状态
getSelectedRowModel() - 返回选定的行
getFilteredSelectedRowModel() - 过滤后返回选定的行
getGroupedSelectedRowModel() - 分组和排序后返回选定的行

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 将只返回当前页上的选定行，因为表格行模型只能根据传入的数据生成行。然而，行选择状态可以很好地包含数据数组中不存在的行 ID。

管理行选择状态

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

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

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

有用的行 ID

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

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

现在，当行被选中时，行选择状态将看起来像这样：

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

而不是这样：

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

有条件地启用行选择

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

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

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

单行选择

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

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

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

子行选择

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

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 来直接设置行选择状态，就像您使用任何其他状态更新程序一样。这些处理函数只是一种方便。

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 也适用于此用例。

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

行固定指南

排序指南