TanStack Table React 行选择(Row Selection)实战指南:原子状态、Shift 范围选择与子行级联

原创2026-09-20 10:36:571,944 阅读
文章标签:前端UI组件

TanStack Table React 行选择(Row Selection)实战指南:原子状态、Shift 范围选择与子行级联

本指南围绕 docs/framework/react/guide/row-selection.md 展开,讲解在 React 应用中为表格接入行选择功能的完整路径:从 tableFeatures({ rowSelectionFeature }) 的特性注册、table.state.rowSelection 与外部 atom 两种状态管理模式、getRowId 的稳定标识设计,到条件启用、单选、子行级联、Shift 范围选择以及复选框/整行点击两类 UI 渲染方案。读完本文,你将能基于 v9 的细粒度订阅机制实现带"全选/当前页全选/半选态"、支持 Shift 区间批量操作、且状态可跨组件共享的行选择表格。

1. 特性总览:rowSelectionFeature 是什么

行选择是 TanStack Table 的核心交互能力之一。在 v9 架构中,所有能力都以 feature 的形式注册到表格实例上——行选择对应 rowSelectionFeature,它位于 packages/table-core/src/features/row-selection/rowSelectionFeature.ts,由三部分文件组成:

  • rowSelectionFeature.ts:特性注册本身,声明初始状态、默认选项,并把行级 API 挂到 row 原型、把表级 API 挂到 table 实例;
  • rowSelectionFeature.utils.ts:全部状态读写、勾选处理器、范围选择的实际实现;
  • rowSelectionFeature.types.ts:RowSelectionState、ToggleSelectedOptions 以及所有行级/表级 API 的类型签名。

从源码可以看到该特性提供的默认选项(getDefaultTableOptions):

onRowSelectionChange: makeStateUpdater('rowSelection', table),
enableRowSelection: true,      // 是否允许选择行
enableMultiRowSelection: true, // 是否允许多选
enableRowRangeSelection: true, // 是否启用 Shift 范围选择
enableSubRowSelection: true,   // 选择父行时是否级联选择子行
isRowRangeSelectionEvent: (event) =>
  Boolean(
    (event as { shiftKey?: boolean }).shiftKey ||
    (event as { nativeEvent?: { shiftKey?: boolean } }).nativeEvent?.shiftKey,
  ),

也就是说,只要注册了该特性,行选择能力默认全部开启,无需额外配置即可使用;这些选项后续都可以按需覆盖。

1.1 React 侧如何注册

React 包从 @tanstack/react-table 导出 tableFeatures 与 rowSelectionFeature。useTable 内部通过 constructTable 构造实例时,会把 React 的响应式绑定(reactReactivity)合并进 features(见 packages/react-table/src/useTable.ts),因此行选择状态天然与 React 渲染周期对齐。

import {
  useTable,
  tableFeatures,
  rowSelectionFeature,
} from '@tanstack/react-table'

const features = tableFeatures({ rowSelectionFeature })

const table = useTable({
  features,
  columns,
  data,
})

rowSelectionFeature 还常与分页、筛选、全局筛选等特性组合使用。仓库中的完整示例见 examples/react/row-selection/src/main.tsx,它同时注册了 rowPaginationFeature、columnFilteringFeature、globalFilteringFeature 及对应的 row model,正好演示"筛选 + 分页 + 行选择"协同工作的生产级组合。

2. 读取行选择状态

行选择状态本身是一个以行 id 为 key 的映射(RowSelectionState = Record<string, true>,见 rowSelectionFeature.types.ts)。表格实例自动管理这份状态,并提供多个读取入口:

API 说明
table.state.rowSelection 响应式读取行选择状态(经 useTable selector 订阅)
table.getSelectedRowModel() 从核心 row model(未筛选未分组)中筛出已选行
table.getFilteredSelectedRowModel() 从筛选后的 row model 中筛出已选行
table.getGroupedSelectedRowModel() 从分组/排序后的 row model 中筛出已选行
table.getSelectedRowIds() 返回所有已选行的 id 数组
table.atoms.rowSelection.get() 非渲染代码中读取当前快照,不建立订阅
console.log(table.state.rowSelection) // { 1: true, 2: false, ... }
console.log(table.getSelectedRowModel().rows) // 全量客户端已选行
console.log(table.getFilteredSelectedRowModel().rows) // 筛选后已选行
console.log(table.getGroupedSelectedRowModel().rows) // 分组后已选行

从源码看,三个 get*SelectedRowModel 的 memoDeps 分别绑定到 table.atoms.rowSelection 与对应的上游 row model(core / filtered / sorted),见 rowSelectionFeature.ts,因此它们都会在筛选、排序或选择状态变化时自动重算。

2.1 渲染位置与非渲染位置的读取差异

  • 渲染位置:优先使用 table.state.rowSelection(useTable 的 selector 负责订阅并触发 re-render),或 table.Subscribe 做定点订阅,粒度更细(可只订阅某个行 id 对应的值)。
  • 非渲染位置(事件回调、async 逻辑):table.atoms.rowSelection.get() 直接读快照,不会让组件订阅未来的变化。

这也是 useTable 返回的 state 与底层 store 的设计分工——useTable 支持通过第二个参数传入 selector 来裁剪订阅范围(见 useTable.ts)。

2.2 与 manualPagination 的注意事项

[!NOTE] 若使用 manualPagination(服务端分页),getSelectedRowModel 系列 API 只会返回当前 data 中存在的已选行,因为 row model 只能基于传入的 data 生成行。但行选择状态本身可以保存 data 中不存在的行 id——比如跨页记录之前选中的 id。

这一设计在源码中体现得很清楚:selectRowsFn 的注释明确指出"selected ids absent from that model are not materialized as rows"(见 rowSelectionFeature.utils.ts)。

3. 管理行选择状态:两种受控模式

如果只是表格内部使用,useTable 自动管理的内部状态就够了。但当你需要在其他组件(例如工具栏"已选 N 项"、批量操作按钮、提交 API 的 payload)里读取或写入选择状态时,v9 提供了两种受控模式。

3.1 推荐:外部 atom(v9 原生方案)

v9 基于 TanStack Store 的 atom 体系实现细粒度订阅。把 rowSelection atom 通过 atoms 选项交给表格后,所有选择 API 都会直接更新这个 atom,你可以在应用任意位置 useSelector 读取,不会因为读取选择状态而迫使表格所在组件重新渲染。

import { useCreateAtom, useSelector } from '@tanstack/react-store'
import {
  useTable,
  tableFeatures,
  rowSelectionFeature,
  type RowSelectionState,
} from '@tanstack/react-table'

const features = tableFeatures({ rowSelectionFeature })

const rowSelectionAtom = useCreateAtom<RowSelectionState>({})

// 在任意组件中订阅该值
const rowSelection = useSelector(rowSelectionAtom)

const table = useTable({
  features,
  //...
  atoms: {
    rowSelection: rowSelectionAtom, // 选择 API 现在更新 rowSelectionAtom
  },
})

这正是 examples/react/row-selection/src/main.tsx 的用法:示例把 rowSelection 提升到外部 atom,并在页面底部直接渲染 Object.keys(table.state.rowSelection).length 作为选中计数。由于 atom 与表格状态同源,即便用 getToggleAllRowsSelectedHandler() 等 API 触发的更新,也会同步反映到该 atom 上。

3.2 兼容 v8:state + onRowSelectionChange

v8 风格的两件套仍然支持,适合简单集成或从 v8 迁移的存量代码,但订阅粒度不如外部 atom 细:

const [rowSelection, setRowSelection] = useState<RowSelectionState>({})

const table = useTable({
  features,
  //...
  onRowSelectionChange: setRowSelection,
  state: {
    rowSelection,
  },
})

关于两种模式更深入的取舍对比,可参考 docs/framework/react/guide/table-state.md。从类型定义看,onRowSelectionChange 接收一个 OnChangeFn<RowSelectionState>,既可以直接传 setter,也可以传 (updater) => ... 形式的自定义回调(见 rowSelectionFeature.types.ts)。

4. 使用稳定的行 id:getRowId

行选择状态以 row id 作为 key。默认情况下 row id 就是 row.index(行在数组中的下标),这意味着插入、删除、重排数据时选择会"错位"。对于需要持久化选择的场景(数据库行、跨页选择、与后端交互),务必用 getRowId 返回稳定且唯一的标识:

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

选择后状态会从这种形态:

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

变成:

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

示例项目的数据生成器(examples/react/row-selection/src/makeData.ts)为每条 Person 记录生成了 id,并在 useTable 中配置 getRowId: (row) => row.id。配套的 e2e 测试也依赖这一点——测试注释明确写道"Row ids are uuids, so only the number of selected keys is assertable"(见 smoke.spec.ts)。选择以 id 为 key 还有一个附带收益:翻页后已选行仍然保持选中,e2e 测试 selects every row across all pages from the header 专门验证了这一点——全选后翻到下一页,页脚全选框依旧处于勾选状态。

5. 条件启用行选择

enableRowSelection 默认为 true(全部行可选)。它接受布尔值或行级谓词函数,用于按条件放行或整体关闭:

const table = useTable({
  //...
  enableRowSelection: (row) => row.original.age > 18, // 仅成年行可选
})

UI 侧用 row.getCanSelect() 判断该行是否可选,例如据此禁用复选框。底层实现上,row_getCanSelect 就是透传这个选项:函数形式则调用谓词,布尔形式则直接返回(见 rowSelectionFeature.utils.ts)。

需要说明的是,getToggleSelectedHandler 对不可选行是安全 no-op——处理器开头就会 if (!canSelect) return(见 rowSelectionFeature.utils.ts),所以即使忘了在 UI 上禁用,直接调用处理器也不会误选。

6. 单行选择:radio 风格

默认允许多选。enableMultiRowSelection 设为 false 即切换为"同时最多一行",适合用 radio 替代 checkbox 的场景;同样也支持谓词形式,按行决定该行是否参与多选:

const table = useTable({
  //...
  enableMultiRowSelection: false, // 同一时刻只允许选择一行
  // enableMultiRowSelection: row => row.original.age > 18, // 仅成年人参与多选
})

实现层面的关键点:row_toggleSelected 在选中时若发现 !row_getCanMultiSelect(row),会清空整个选择映射再写入当前行,从而保证单选语义(见 rowSelectionFeature.utils.ts 中 mutateRowIsSelected 对多选能力的处理)。

7. 子行级联选择

enableSubRowSelection 控制"选中父行时是否一并选中其子行",默认 true。对树形/展开型表格(配合 expanding、grouping 特性)尤为关键:

const table = useTable({
  //...
  enableSubRowSelection: false, // 禁止级联选择子行
  // enableSubRowSelection: row => row.original.age > 18, // 谓词按行控制
})

级联对"全选" API 同样生效:当父行阻止子行选择时,table.toggleAllRowsSelected() 与 table.toggleAllPageRowsSelected() 会跳过该父行的所有后代;table.getIsAllRowsSelected() 与 table.getIsAllPageRowsSelected() 在判定"是否全选"时也会忽略这些被阻挡的后代。源码中 isRowSelectableInSelectAll 实现了这条规则——它向上遍历祖先链,一旦某层祖先不允许子行选择,整个子树都不可达,并用 subtreeCache 缓存每个祖先的判定结果,避免共享祖先链被重复遍历(见 rowSelectionFeature.utils.ts)。

7.1 关于父行 id 的"残留"

选中父行会把父行 id 与其可选后代 id 一并写入选择状态。之后单独取消某个子行,默认情况下父行 id 不会被移除——因为选择状态被视为字面意义上的"哪些 id 被选中"。如果希望取消子行时顺带清理祖先 id,可给 toggle API 传 deselectParents: true:

row.getToggleSelectedHandler({ deselectParents: true })
// 或
row.toggleSelected(false, { deselectParents: true })

ToggleSelectedOptions 类型对该选项的说明指出:当父行级联把父 id 写入状态、而子行随后被取消时,此选项用于清除这些过期的父 id(见 rowSelectionFeature.types.ts)。实现上 pruneAncestorRowIds 会沿 parentId 链一路上溯删除所有祖先 id(见 rowSelectionFeature.utils.ts)。

8. Shift 范围选择

row.getToggleSelectedHandler() 默认内置 Shift 范围选择:先点击某行建立锚点(anchor),再按住 Shift 点击另一行,即可将两行之间的闭区间(含两端点)整段选中或取消。区间选中/取消的结果由被点击的复选框当前值决定,被点击的端点会成为下一次 Shift 操作的锚点。

关键行为要点:

  • 事件识别:处理器通过 event.shiftKey || event.nativeEvent.shiftKey 识别 Shift。React 的 checkbox onChange 事件把底层 click 暴露在 nativeEvent 上,所以下例能正确感知修饰键。
  • 可配置的检测函数:enableRowRangeSelection: false 可整体关闭;isRowRangeSelectionEvent 可自定义判定逻辑(例如用平台修饰键 Meta 代替 Shift)。
  • 显示顺序敏感:范围基于表格当前逻辑显示顺序(包含筛选、分组、排序、展开后的结果)。客户端分页时范围可以跨页(因为使用的是完整的分页前顺序);手动/服务端分页时只有当前 data 中加载的行能参与。
const table = useTable({
  // ...
  enableRowRangeSelection: false,

  // 例如改用平台修饰键代替 Shift:
  // isRowRangeSelectionEvent: event =>
  //   Boolean((event as React.MouseEvent).metaKey),
})
// 行级:仅对显示顺序区间内明确出现的行生效(不级联后代)
<Checkbox
  checked={row.getIsSelected()}
  onChange={row.getToggleSelectedHandler({ selectChildren: false })}
/>

selectChildren: false 用于控制:默认情况下,区间内遇到的父行在子行选择启用时会递归级联其可选后代;传 false 则只改变区间内明确出现的行。

8.1 锚点的生命周期

锚点(内部记录在 table._lastSelectedRowId,见 rowSelectionFeature.ts)在排序、筛选、分组、展开、分页乃至数据更新期间都会保留——只要其行 id 仍在显示顺序中。规则如下:

  • 若筛选或数据替换使锚点行消失,下一次 Shift 交互退化为普通行切换,并建立新锚点;
  • resetRowSelection、任一全选 API、table.reset() 会清除锚点;
  • 直接调用 row.toggleSelected()、table.setRowSelection() 或受控状态的外部修改,不会建立或移动锚点。

区间判定实现在 selectRowRange 中:它先从分页前的 row model 解析锚点行(找不到则退回 core row model),再校验两端点的显示索引仍指向同一行、且两端点都支持多选;通过后对闭区间内的行逐行执行 mutateRowIsSelected(不可选/不可多选的行跳过),并返回 false 表示应回退为普通切换(见 rowSelectionFeature.utils.ts)。

e2e 测试 selects an inclusive range with Shift-click 验证了闭区间语义:先勾选第 2 行建立锚点,再 Shift 点击第 6 行,最终选中 1~5 行共 5 行(含两端点),第 1 行与第 7 行不受影响(见 smoke.spec.ts)。

9. 渲染行选择 UI

TanStack Table 不规定 UI 形态——checkbox、radio,或直接把点击事件挂到整行都行。表格实例提供了一批现成的处理器 API,让 UI 渲染与状态更新解耦。

9.1 接入 Checkbox

处理器会自动调用内部 API 更新状态并触发重渲染:

  • row.getToggleSelectedHandler():切换某行的选择状态;
  • table.getToggleAllRowsSelectedHandler():切换全部行的选择(全表全选);
  • table.getToggleAllPageRowsSelectedHandler():切换当前页行的选择(页级全选)。

需要更精细控制时,也可以绕开处理器直接使用底层 API:row.toggleSelected()、table.toggleAllRowsSelected(),或直接用 table.setRowSelection(updater) 像更新其他状态一样写入选择映射。处理器本质上只是便捷封装。

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

[!NOTE] 行 checkbox 上的 getCanSelectSubRows() 与 getIsAllSubRowsSelected() 子句仅对存在子行的表格有意义;扁平数据只需 row.getIsSelected()。包含 deselectParents 完整模式的写法可参考 expanding 示例。

示例项目中的 IndeterminateCheckbox 组件展示了半选态的正确实现:通过 ref.current.indeterminate = !rest.checked && indeterminate 设置原生 indeterminate 属性(见 main.tsx)。表头 checkbox 绑定 getIsAllRowsSelected/getIsSomeRowsSelected(跨所有页),表尾 checkbox 绑定 getIsAllPageRowsSelected/getIsSomePageRowsSelected(仅当前页)。e2e 测试对这一布局做了完整断言:选中 1 行时两个全选框都进入半选态;页尾全选 10 行后,页头仍因全局 1000 行只选了 10 行而保持半选(见 smoke.spec.ts)。

9.2 整行点击选择

更简单的交互是整行绑定点击事件——row.getToggleSelectedHandler() 同样适用,例如用 row.getIsSelected() 控制行高亮:

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

10. 实践要点小结

  1. 注册即用:tableFeatures({ rowSelectionFeature }) 一行接入,全部选择 API 自动可用,默认多选、默认 Shift 范围选择、默认子行级联。
  2. 优先外部 atom:需要在表格外共享/读取选择状态时,atoms.rowSelection 是 v9 推荐方案,订阅粒度细、不拖累表格组件重渲染;v8 风格 state.rowSelection + onRowSelectionChange 依然兼容。
  3. 稳定 id 是前提:生产环境务必 getRowId 返回数据库主键/uuid,选择状态才会在数据增删、排序、翻页后依然正确。
  4. 读状态的姿势分场景:渲染用 table.state.rowSelection(或 table.Subscribe 定点订阅),事件回调用 table.atoms.rowSelection.get() 快照。
  5. 范围选择随显示顺序走:Shift 区间会遵循当前筛选/排序/分组/展开后的逻辑顺序,客户端分页可跨页,服务端分页仅限当前 data;锚点在重置/全选时被清除。
  6. 级联与清理:父行选中级联子行;取消子行默认不清父 id,需要时传 deselectParents: true;enableSubRowSelection 的谓词形式可精确控制哪些父行不参与级联。

参考资源

登录后查看全文
table