TanStack Solid Table 行选择(Row Selection)完整实战指南:从状态管理到 Shift 区间选择
TanStack Solid Table 行选择(Row Selection)完整实战指南:从状态管理到 Shift 区间选择
本指南以 TanStack Table v9 的 Solid 适配包 @tanstack/solid-table 为主线,系统讲解行选择(Row Selection)特性的配置、状态读写、条件启用、父子行联动与 Shift 区间选择等完整能力。读完本文,你将掌握如何在自己的 Solid 应用中接入行选择复选框、用外部 atom 托管选中状态、为批量操作读取选中行,以及复现 官方 Solid 行选择示例 中"10 万行级压测下依然保持选中状态持久"的完整实现方案。
一、什么是行选择特性
行选择(Row Selection)是 TanStack Table 的核心交互特性之一:它跟踪"哪些行被选中",并提供一整套 API 让你以各种方式切换行的选中状态。在 @tanstack/solid-table 中,该能力由 rowSelectionFeature 提供,通过 tableFeatures 组合器注册进表格实例。
从源码看,行选择特性本身只是表格的一个 Feature 模块,它负责:
- 在初始状态中注册
rowSelection状态切片(默认值为空对象{}); - 为表格实例挂载
getSelectedRowModel、toggleAllRowsSelected、getIsAllRowsSelected等表格级 API; - 为行对象挂载
getIsSelected、getCanSelect、getToggleSelectedHandler等行级 API; - 维护一个内部锚点
_lastSelectedRowId,供 Shift 区间选择使用(见第六节)。
1.1 基础接入:注册特性并创建表格
在 Solid 中,createTable 接收的选项对象需要以 getter 形式暴露响应式输入(例如 data),这样 Solid 的信号变化才能被表格正确追踪:
import {
createTable,
tableFeatures,
rowSelectionFeature,
} from '@tanstack/solid-table'
const features = tableFeatures({ rowSelectionFeature })
const table = createTable({
features,
columns,
get data() {
return data()
},
})
接入 rowSelectionFeature 后,与行选择相关的全部 API 即自动生效。完整可运行示例见 examples/solid/row-selection,该示例还同时组合了 rowPaginationFeature、columnFilteringFeature、globalFilteringFeature 与 createPaginatedRowModel,并通过 getRowId: (row) => row.id 用 UUID 作为行 id(示例中的核心配置见 App.tsx)。
二、读取行选择状态
表格实例已经替你管理了行选择状态,你可以通过以下 API 读取"选中的行":
| API | 返回值说明 |
|---|---|
table.atoms.rowSelection.get() |
原始行选择状态(一个 { rowId: boolean } 映射,被读取时是响应式的) |
getSelectedRowModel() |
基于核心行模型筛选出的选中行 |
getFilteredSelectedRowModel() |
过滤之后仍被选中的行 |
getGroupedSelectedRowModel() |
分组、排序之后仍被选中的行 |
console.log(table.atoms.rowSelection.get()) //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
2.1 Solid 响应式读取语义
在 Solid 中,表格的状态 atom 由 Solid 信号支撑,因此:
- 在追踪作用域内(JSX、
createMemo、createEffect、table.Subscribe)调用table.atoms.rowSelection.get()是响应式读取,状态变化会触发该作用域重算; - 在事件处理器等非追踪代码中,同样的调用只是返回当前值。
createTable 的实现(packages/solid-table/src/createTable.ts)展示了这种机制的来源:表格通过 solidReactivity 桥接 TanStack Store 的 atom,并暴露了 table.Subscribe 组件用于创建"只追踪所读 atom"的细粒度渲染边界。示例中通过 table.store.get() 直接序列化整个状态树到页面(见 App.tsx),也是基于同一套 store 机制。
2.2 三种选中行模型的差别
getSelectedRowModel():从核心(core)行模型投影出选中行,即"全量数据里被选中的行";getFilteredSelectedRowModel():从过滤后的行模型投影,适合"在当前搜索结果里选中的行";getGroupedSelectedRowModel():从排序后(含分组回退链)的行模型投影,适合树形/分组数据。
从源码看,这三个 API 都经由 selectRowsFn 递归构建选中行模型,且当没有任何行被选中时会直接返回空模型,避免遍历(rowSelectionFeature.utils.ts)。此外还有 table.getSelectedRowIds() 直接返回选中行 id 数组,供批量调用等场景使用。
[!NOTE] 若你启用了
manualPagination(手动分页),getSelectedRowModel只会返回当前 data 里能匹配到的选中行,因为行模型只能基于传入的data生成。但rowSelection状态本身可以合法地包含 data 中不存在的行 id。
三、管理行选择状态:外部 atom 与受控模式
如果你需要在应用其他位置方便地拿到选中行 id(例如发起批量 API 调用),推荐自己持有 rowSelection 状态切片。
3.1 推荐:外部 atom(v9 首选)
v9 的推荐做法是通过 atoms 表格选项传入外部 atom。atom 保留细粒度订阅能力,选中值可以在应用的任何位置被读取,而不会让表格依赖组件局部状态:
import { createAtom, useSelector } from '@tanstack/solid-store'
import {
createTable,
tableFeatures,
rowSelectionFeature,
type RowSelectionState,
} from '@tanstack/solid-table'
const features = tableFeatures({ rowSelectionFeature })
const rowSelectionAtom = createAtom<RowSelectionState>({})
// subscribe to the atom wherever you need the value
const rowSelection = useSelector(rowSelectionAtom)
const table = createTable({
features,
//...
atoms: {
rowSelection: rowSelectionAtom, // selection APIs now update rowSelectionAtom
},
})
此后所有选择 API(toggleSelected、getToggleSelectedHandler、toggleAllRowsSelected 等)写入的都将是 rowSelectionAtom,你在组件里用 useSelector 读到的是同一份响应式数据。示例工程中把 atoms: { rowSelection: rowSelectionAtom } 作为可选配置写入了注释(见 App.tsx)。
3.2 兼容:v8 风格的受控状态
state.rowSelection + onRowSelectionChange 的 v8 风格模式依然受支持,适合简单集成或从 v8 迁移的场景,但它的细粒度不如外部 atom:
const [rowSelection, setRowSelection] = createSignal<RowSelectionState>({})
const table = createTable({
features,
//...
state: {
get rowSelection() {
return rowSelection() // connect the signal back down to the table
},
},
onRowSelectionChange: setRowSelection,
})
两种模式如何取舍,可参考 Solid 表格状态指南 中的深入对比。值得一提的是,源码中 onRowSelectionChange 的默认实现就是 makeStateUpdater('rowSelection', table),它会把状态写回表格内部(rowSelectionFeature.ts);而 table.setRowSelection 则把更新器直接路由到 onRowSelectionChange(rowSelectionFeature.utils.ts),这正是"内部状态 / 外部 atom / 受控信号"三种模式可以自由切换的底层原因。
四、使用有意义的行 id
默认情况下,每一行的行 id 就是 row.index(如 0、1、2)。但行选择状态是按行 id 作为键来存储的,一旦数据排序、过滤或分页,基于索引的 id 会让选中状态错乱。因此使用行选择时,强烈建议通过 getRowId 指定一个稳定的唯一行 id:
const table = createTable({
features,
//...
getRowId: (row) => row.uuid, // use the row's uuid from your database as the row id
})
配置后,选中状态将是:
{
"13e79140-62a8-4f9c-b087-5da737903b76": true,
"f3e2a5c0-5b7a-4d8a-9a5c-9c9b8a8e5f7e": false
//...
}
而不是:
{
"0": true,
"1": false
//...
}
示例工程使用 makeData 生成的 UUID 作为 id(getRowId: (row) => row.id),其 e2e 测试特意注释"行 id 是 UUID,所以只能断言选中键的数量",可见稳定 id 对断言与状态持久性的重要性(smoke.spec.ts)。e2e 测试还验证了:全选后翻页,下一页的行"因为按 id 而非位置存储,天然保持选中"(smoke.spec.ts)。
五、条件启用与单选模式
5.1 按行条件启用选中
行选择默认对全部行开启。通过 enableRowSelection 选项,你可以传入布尔值整体开关,或传入函数做更细粒度的控制:
const table = createTable({
//...
enableRowSelection: (row) => row.original.age > 18, //only enable row selection for adults
})
在 UI 上,用 row.getCanSelect() 判断该行是否可选,来决定是否禁用复选框或其他选择控件。源码中 enableRowSelection 的默认值为 true,当它是函数时会对每一行求值(rowSelectionFeature.utils.ts)。示例工程里用一个 enableRowSelection 信号驱动这个选项,并提供了"Enable/Disable Row Selection"切换按钮来演示整体开关(App.tsx)。
5.2 单选模式(radio 按钮场景)
默认允许多行同时选中。若只想允许同时选中一行(例如用 radio 按钮代替复选框的表格),把 enableMultiRowSelection 设为 false;也可以传入函数,对某一行的子行条件性地禁用多选:
const table = createTable({
//...
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
})
从实现看,mutateRowIsSelected 在"选中一个不支持多选的行"时会先清空整个选择映射再写入当前行,从而保证单选语义(rowSelectionFeature.utils.ts)。
六、父子行(子行)选择
6.1 子行联动开关
默认选中父行会连带选中其所有子行。通过 enableSubRowSelection 可整体禁用,或按行条件禁用:
const table = createTable({
//...
enableSubRowSelection: false, //disable sub-row selection
// enableSubRowSelection: row => row.original.age > 18, //disable sub-row selection for adults
})
子行选择同样作用于全选 API:当父行阻止子行选择时,table.toggleAllRowsSelected() 与 table.toggleAllPageRowsSelected() 会跳过该父行的后代;table.getIsAllRowsSelected() 与 table.getIsAllPageRowsSelected() 在判断"是否全选"时也会忽略这些后代。这一点在源码中有专门优化:全选级联通过 subtreeCache 记忆"每棵子树是否可达",避免对共享祖先链重复求值 enableSubRowSelection(rowSelectionFeature.utils.ts)。
6.2 父 id 的写入与清理(deselectParents)
选中父行时,父行 id 及其可选的子行 id 都会写入选择状态。默认情况下,之后反选某个子行并不会移除父行 id——因为有些表格把状态里的 id 视为"字面上的选中项"。如果你希望"反选子行时同步清理祖先 id",请给切换 API 传入 deselectParents 选项:
row.getToggleSelectedHandler({ deselectParents: true })
// or
row.toggleSelected(false, { deselectParents: true })
源码中 pruneAncestorRowIds 会沿 parentId 链向上删除所有祖先 id,且刻意不判断 getCanSelect——因为"反选子行必然使'全部子行已选'失效",遗留的父 id 恰恰是它要消除的陈旧状态(rowSelectionFeature.utils.ts)。
七、Shift 区间选择(Range Selection)
row.getToggleSelectedHandler() 默认内置 Shift 区间选择能力:
- 一次普通点击选中某行后,该行成为"锚点";
- 按住 Shift 点击另一行,会选中(或反选)两行之间的闭区间(包含两端);
- 整个区间的选中值由点击端复选框的最终 checked 值决定;
- 点击端会成为下一次 Shift 交互的新锚点。
处理函数通过 event.shiftKey 或 event.nativeEvent.shiftKey 识别 Shift 修饰键。注意:在 Solid 中绑定复选框处理函数要用 onClick 而非 onChange,这样才能拿到携带 shiftKey 的点击事件。
你可以关闭区间选择,或替换事件识别逻辑:
const table = createTable({
// ...
enableRowRangeSelection: false,
// For example, use the platform modifier instead of Shift:
// isRowRangeSelectionEvent: event =>
// Boolean((event as { metaKey?: boolean }).metaKey),
})
源码中 enableRowRangeSelection 与 isRowRangeSelectionEvent 的默认值分别为 true 与"检查 shiftKey/nativeEvent.shiftKey"(rowSelectionFeature.ts)。锚点 _lastSelectedRowId 由特性在初始化与重置时归零(rowSelectionFeature.ts)。
7.1 区间选择的边界行为
- 遵循逻辑显示顺序:区间按表格当前的逻辑显示顺序(含过滤、分组、排序、展开)计算;客户端分页时区间可以跨页,因为使用的是分页前的完整顺序;手动/服务端分页时,只有当前
data内加载的行能参与。 - 子行递归:默认区间内遇到父行会递归切换其可选子行;若只想改变"区间内明确出现的行",传
selectChildren: false:
const handler = row.getToggleSelectedHandler({
selectChildren: false,
})
- 锚点存活性:锚点在排序、过滤、分组、展开、分页及数据更新后依然保留,只要其行 id 仍存在于显示顺序中。若过滤或数据替换移除了锚点,下一次 Shift 交互退化为普通行切换并建立新锚点。
- 锚点清除时机:
resetRowSelection、任意全选 API、table.reset()都会清除锚点;直接调用row.toggleSelected()、table.setRowSelection()或外部受控状态变化不会建立或移动锚点。
e2e 测试实证了区间行为:先点击第 2 行建立锚点,再 Shift 点击第 6 行,恰好选中第 1~5 行的 5 行闭区间(行 0 与行 6 不受影响)(smoke.spec.ts)。
八、渲染行选择 UI
TanStack Table 不规定你如何渲染选择 UI——复选框、radio、或直接把点击事件挂到行上都行。它只提供若干 API 帮你接线。
8.1 复选框模式:head 全选 + 行选择
把 getToggleSelectedHandler 系列 API 直接绑定到复选框即可,它们会自动调用内部 API 更新状态并重渲染:
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() ||
(row.getCanSelectSubRows() && row.getIsAllSubRowsSelected())
}
disabled={!row.getCanSelect()}
indeterminate={row.getIsSomeSelected()}
onClick={row.getToggleSelectedHandler()}
/>
),
},
//... more column definitions...
]
[!NOTE] 行复选框上的
getCanSelectSubRows()与getIsAllSubRowsSelected()只对含子行的表格有意义;扁平数据下仅row.getIsSelected()即可。父子行场景的完整写法(含用deselectParents清理陈旧父 id)可参考 expanding 示例。需要更细粒度控制时,也可以直接用row.toggleSelected()、table.toggleAllRowsSelected(),或干脆用table.setRowSelection()像更新其他状态一样直接设置选择状态——这些 handler 本质上只是便捷封装。
示例工程对上述模式做了完整落地,并且有个细节值得学习:由于表头复选框绑定在 tableRef.current 上,它先通过 tableRef 在组件挂载后拿到表格实例,再在 header 渲染函数中调用表格 API(App.tsx)。同时它自实现了 IndeterminateCheckbox 组件,用 createEffect 在每次渲染后同步 DOM 的 indeterminate 属性(App.tsx)。
8.2 更简单的方案:整行点击
如果希望点击整行即可切换选中,row.getToggleSelectedHandler() 同样适用:
<tbody>
<For each={table.getRowModel().rows}>
{(row) => (
<tr
classList={{ selected: row.getIsSelected() }}
onClick={row.getToggleSelectedHandler()}
>
<For each={row.getVisibleCells()}>{(cell) => <td>{/* */}</td>}</For>
</tr>
)}
</For>
</tbody>
8.3 三个"全选"复选框的语义差异
示例页面同时放了三个全选框(App.tsx 与 App.tsx),它们对应不同 API:
| 复选框 | 绑定 API | 语义 |
|---|---|---|
| 表头全选 | getIsAllRowsSelected / getToggleAllRowsSelectedHandler |
所有页的全部行 |
| 表尾全选 | getIsAllPageRowsSelected / getToggleAllPageRowsSelectedHandler |
仅当前页的行 |
e2e 测试验证了二者的差异:勾选表尾全选只选中 10 行(当前页),表头仍显示"部分选中";勾选表头全选则选中全部 1000 行,且翻页后新页行保持选中(smoke.spec.ts)。table.getIsSomeRowsSelected() / table.getIsSomePageRowsSelected() 则分别用于计算两个复选框的半选(indeterminate)状态。
九、实战:一个带分页、过滤与压测的行选择表格
把上面的知识点串起来,就是 examples/solid/row-selection 示例的全貌。它展示了行选择与分页、过滤等特性协同工作时的完整形态:
- 响应式数据:
createSignal(makeData(1_000))作为数据源,get data() { return data() }暴露给表格;"Regenerate Data" 与 "Stress Test (1M rows)" 按钮分别重新生成 1000 行与 100 万行数据,验证大体积数据下的选择性能与状态稳定性; - 全局搜索:通过
table.atoms.globalFilter.get()与table.setGlobalFilter()接入全局过滤,行选择状态在过滤前后保持不变(e2e 测试专门验证了这一点,smoke.spec.ts); - 选中计数摘要:用
table.atoms.rowSelection.get()的键数量除以table.getPreFilteredRowModel().rows.length显示"X of 1,000 Total Rows Selected"; - 状态检查面板:
table.store.get()将完整状态树 JSON 序列化到页面,便于调试; - Devtools 集成:
useTanStackTableDevtools(table)接入 Solid 版 devtools,同时用key: 'row-selection'为表格命名(App.tsx)。
运行该示例的方式:进入 examples/solid/row-selection 目录后安装依赖并启动 Vite 开发服务器(package.json 中已配置好 scripts),即可在浏览器中交互验证以上全部行为;仓库内还配套了 Playwright e2e 测试,覆盖渲染、单行选择、Shift 区间、页级/全局全选、过滤持久性与分页大小联动等关键场景,可作为你编写自己测试用例的参考模板。
十、要点速查
| 目标 | 选项 / API | 默认值 |
|---|---|---|
| 整体启用行选择 | enableRowSelection(布尔或行谓词) |
true |
| 允许多选 | enableMultiRowSelection(布尔或行谓词) |
true |
| 选中父行联动子行 | enableSubRowSelection(布尔或行谓词) |
true |
| Shift 区间选择 | enableRowRangeSelection + isRowRangeSelectionEvent |
true / 检测 shiftKey |
| 反选时清理祖先 id | toggleSelected(false, { deselectParents: true }) |
关闭 |
| 区间内不递归子行 | getToggleSelectedHandler({ selectChildren: false }) |
递归 |
| 使用稳定行 id | getRowId: (row) => row.uuid |
行索引 |
| 读取选中状态 | table.atoms.rowSelection.get() |
响应式读取 |
| 托管选中状态 | atoms.rowSelection(推荐)或 state + onRowSelectionChange |
内部状态 |
| 选中行模型 | getSelectedRowModel / getFilteredSelectedRowModel / getGroupedSelectedRowModel |
分别基于 core / filtered / sorted 模型 |
| 全选 API | toggleAllRowsSelected / toggleAllPageRowsSelected(含对应 handler 与 getIsAll* 查询) |
— |
| 行级能力查询 | getCanSelect / getCanMultiSelect / getCanSelectSubRows / getIsAllSubRowsSelected / getIsSomeSelected |
— |
以上所有默认值与行为,均可直接在本仓库源码中核对:特性注册与默认选项、状态与切换逻辑实现、类型定义。Solid 适配层的响应式桥接见 packages/solid-table/src/createTable.ts 与 packages/solid-table/src/reactivity.ts。