行选择指南

示例

想直接看实现？可以参考以下示例

API

行选择 API

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

访问行选择状态

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

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

console.log(table.getState().rowSelection) //get the row selection state - { 1: true, 2: false, etc... }
console.log(table.getSelectedRowModel().rows) //get full client-side selected rows
console.log(table.getFilteredSelectedRowModel().rows) //get filtered client-side selected rows
console.log(table.getGroupedSelectedRowModel().rows) //get grouped client-side selected rows

console.log(table.getState().rowSelection) //get the row selection state - { 1: true, 2: false, etc... }
console.log(table.getSelectedRowModel().rows) //get full client-side selected rows
console.log(table.getFilteredSelectedRowModel().rows) //get filtered client-side selected rows
console.log(table.getGroupedSelectedRowModel().rows) //get grouped client-side selected rows

注意：如果你正在使用 manualPagination，请注意 getSelectedRowModel API 只会返回当前页上的选定行，因为表行模型只能基于传入的 data 来生成行。然而，行选择状态可以包含不在 data 数组中的行 ID。

管理行选择状态

尽管表实例会为你管理行选择状态，但通常更方便自己管理状态，以便轻松访问选定的行 ID，你可以用它们来发出 API 调用或其他操作。

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

const [rowSelection, setRowSelection] = useState<RowSelectionState>({}) //manage your own row selection state

const table = useReactTable({
  //...
  onRowSelectionChange: setRowSelection, //hoist up the row selection state to your own scope
  state: {
    rowSelection, //pass the row selection state back to the table instance
  },
})

const [rowSelection, setRowSelection] = useState<RowSelectionState>({}) //manage your own row selection state

const table = useReactTable({
  //...
  onRowSelectionChange: setRowSelection, //hoist up the row selection state to your own scope
  state: {
    rowSelection, //pass the row selection state back to the table instance
  },
})

有用的行 ID

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

const table = useReactTable({
  //...
  getRowId: row => row.uuid, //use the row's uuid from your database as the row id
})

const table = useReactTable({
  //...
  getRowId: row => row.uuid, //use the row's uuid from your database as the row 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 表选项，它接受布尔值或函数以实现更细粒度的控制。

const table = useReactTable({
  //...
  enableRowSelection: row => row.original.age > 18, //only enable row selection for adults
})

const table = useReactTable({
  //...
  enableRowSelection: row => row.original.age > 18, //only enable row selection for adults
})

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

单行选择

默认情况下，表允许一次选择多行。然而，如果你只想一次选择一行，你可以将 enableMultiRowSelection 表选项设置为 false 来禁用多行选择，或者传入一个函数来有条件地为行的子行禁用多行选择。

这对于创建带有单选按钮而不是复选框的表很有用。

const table = useReactTable({
  //...
  enableMultiRowSelection: false, //only allow a single row to be selected at once
  // enableMultiRowSelection: row => row.original.age > 18, //only allow a single row to be selected at once for adults
})

const table = useReactTable({
  //...
  enableMultiRowSelection: false, //only allow a single row to be selected at once
  // enableMultiRowSelection: row => row.original.age > 18, //only allow a single row to be selected at once for adults
})

子行选择

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

const table = useReactTable({
  //...
  enableSubRowSelection: false, //disable sub-row selection
  // enableSubRowSelection: row => row.original.age > 18, //disable sub-row selection for adults
})

const table = useReactTable({
  //...
  enableSubRowSelection: false, //disable sub-row selection
  // enableSubRowSelection: row => row.original.age > 18, //disable sub-row selection for adults
})

渲染行选择 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()} //or getToggleAllPageRowsSelectedHandler
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        onChange={row.getToggleSelectedHandler()}
      />
    ),
  },
  //... more column definitions...
]

const columns = [
  {
    id: 'select-col',
    header: ({ table }) => (
      <Checkbox
        checked={table.getIsAllRowsSelected()}
        indeterminate={table.getIsSomeRowsSelected()}
        onChange={table.getToggleAllRowsSelectedHandler()} //or getToggleAllPageRowsSelectedHandler
      />
    ),
    cell: ({ row }) => (
      <Checkbox
        checked={row.getIsSelected()}
        disabled={!row.getCanSelect()}
        onChange={row.getToggleSelectedHandler()}
      />
    ),
  },
  //... more column definitions...
]

将行选择 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>

行选择指南

示例

API