行选择指南

示例

想要跳过实现步骤？查看这些示例

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，这没有问题。

管理行选择状态

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

使用 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 中强制控制行是否可选择，您可以对您的复选框或其他选择 UI 使用 row.getCanSelect() API。

单行选择

默认情况下，表格允许多行同时被选中。但是，如果您只想允许单行被选中，您可以将 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 表格不规定您应该如何渲染行选择 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