TanStack Solid Table 行选择(Row Selection)完整实战指南:从状态管理到 Shift 区间选择

原创2026-09-20 10:24:53180 阅读
文章标签:前端UI组件

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 区间选择能力:

  1. 一次普通点击选中某行后,该行成为"锚点";
  2. 按住 Shift 点击另一行,会选中(或反选)两行之间的闭区间(包含两端);
  3. 整个区间的选中值由点击端复选框的最终 checked 值决定;
  4. 点击端会成为下一次 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。

登录后查看全文
table