Angular TanStack Table 行选择(Row Selection)完整指南:从状态管理到多选、范围选择与父子行联动
Angular TanStack Table 行选择(Row Selection)完整指南:从状态管理到多选、范围选择与父子行联动
导读
行选择(Row Selection)是数据表格最常用的交互能力之一,它让表格追踪哪些行被选中、支持单选/多选、全选/反选,并能与复选框、单选框或行点击事件直接联动。本文以 TanStack Table(Angular 版)官方指南为骨架,结合仓库内 @tanstack/angular-table 的实现源码与真实示例,系统讲解在 Angular 应用中如何配置 rowSelectionFeature、读写行选择状态、自定义行 ID、条件启用选择、单行选择、父子行(Sub-Row)选择、Shift 范围选择,以及如何把选择状态接到复选框、单选按钮和整行点击上。读完本文,你将掌握一套可直接复制的行选择接入方案,并理解其底层状态模型与信号(Signal)响应式原理。
相关示例可直接参考:Row Selection 与 Row Selection (Signals) 两个 Angular 示例工程。
开启行选择功能:Row Selection Setup
行选择是 TanStack Table 的插件化能力之一,Angular 版通过 tableFeatures({ rowSelectionFeature }) 组合特性后,再把 features 传入 injectTable。加入该特性后,表格实例上会自动挂载整套行选择相关 API(详见后文)。
import { signal } from '@angular/core'
import {
injectTable,
tableFeatures,
rowSelectionFeature,
} from '@tanstack/angular-table'
const features = tableFeatures({ rowSelectionFeature })
export class App {
readonly data = signal(defaultData)
readonly table = injectTable(() => ({
features,
columns,
data: this.data(),
}))
}
从源码看,rowSelectionFeature 是一个标准 TableFeature 对象(见 rowSelectionFeature.ts),它负责四件事:初始化默认状态、注入默认表格选项、扩展 Row 原型方法、构造 Table 级 API。其中默认表格选项值得特别关注,它们定义了行选择的默认行为:
onRowSelectionChange: makeStateUpdater('rowSelection', table),
enableRowSelection: true,
enableMultiRowSelection: true,
enableRowRangeSelection: true,
enableSubRowSelection: true,
isRowRangeSelectionEvent: (event) => {
const rangeEvent = event as {
shiftKey?: boolean
nativeEvent?: { shiftKey?: boolean }
}
return Boolean(rangeEvent.shiftKey || rangeEvent.nativeEvent?.shiftKey)
},
这意味着:行选择默认对所有行开启、允许多选、允许 Shift 范围选择、选中父行时自动选中子行,且范围选择默认由 shiftKey(或其原生事件上的 shiftKey)触发。这些默认值正是下文各小节讲解的各个开关选项的基准。
真实示例的组装方式可参考 examples/angular/row-selection/src/app/table.ts,其中把 rowSelectionFeature 与列过滤、全局过滤、分页等特性组合在一起,并通过 createTableHook 生成了 injectTable、injectTableContext 等 Angular 注入钩子。
读取行选择状态:Access Row Selection State
表格实例已经替你管理了行选择状态。你可以通过下面几个 API 读取当前的选择状态或选中的行:
table.atoms.rowSelection.get()—— 返回当前行选择状态(一个以行 ID 为键的RowSelectionState对象);getSelectedRowModel()—— 返回全量客户端侧选中的行;getFilteredSelectedRowModel()—— 返回过滤之后选中的行;getGroupedSelectedRowModel()—— 返回分组与排序之后选中的行。
console.log(table.atoms.rowSelection.get()) //获取行选择状态 - { 1: true, 2: false, ... }
console.log(table.getSelectedRowModel().rows) //获取全量客户端侧选中行
console.log(table.getFilteredSelectedRowModel().rows) //获取过滤后的选中行
console.log(table.getGroupedSelectedRowModel().rows) //获取分组后的选中行
在 Angular 中,表格 atom 的读取是信号读取,因此在模板表达式、computed(...) 或 effect(...) 中调用 table.atoms.rowSelection.get() 会自动建立依赖追踪,选择状态变化时相关 UI 会自动更新。这一设计让 Angular 版天然融入 signal 响应式体系,rowSelection 状态的变更不需要像 v8 那样通过整棵组件树重新渲染来传播。
[!NOTE] 如果使用了
manualPagination,请注意getSelectedRowModel只会返回当前页选中的行——因为表格的行模型只能基于传入的data生成。但行选择状态本身可以包含不在data数组中的行 ID,这完全没问题。
与之一致,源码中 table_getSelectedRowModel 等实现均以当前可用的行模型(如过滤/分组/分页后的模型)为输入生成结果,而状态本体 table.atoms.rowSelection 独立存在,这正是"状态可以包含当前页之外的行 ID"这一特性的底层原因。
管理行选择状态:内部托管、外部 Atom 与 Signal 三种模式
推荐方式:外部 Atom 托管
如果你需要在应用其他位置方便地拿到选中的行 ID(例如用来发起 API 请求),推荐在 v9 中把行选择状态切片交给外部 atom 托管。外部 atom 由 @tanstack/angular-store 的 createAtom 创建,并通过 atoms 表格选项传入。Atom 保留细粒度订阅,且选择值可以在应用任意位置读取,不会在每次变化时都重新执行 injectTable 的 options 初始化器。
import { createAtom } from '@tanstack/angular-store'
import {
injectTable,
tableFeatures,
rowSelectionFeature,
} from '@tanstack/angular-table'
import type { RowSelectionState } from '@tanstack/angular-table'
const features = tableFeatures({ rowSelectionFeature })
export class App {
readonly rowSelectionAtom = createAtom<RowSelectionState>({})
readonly table = injectTable(() => ({
features,
//...
atoms: {
rowSelection: this.rowSelectionAtom, // 选择相关 API 现在会更新 rowSelectionAtom
},
}))
// 在任意需要的地方读取 this.rowSelectionAtom.get()
}
当外部 atom 被传入后,表格内部的选择状态读写都会落到这个 atom 上,toggleSelected、toggleAllRowsSelected、setRowSelection 等 API 的变更都会直接反映到 rowSelectionAtom 中。
兼容方式:v8 风格 state + onRowSelectionChange
如果你更熟悉 v8 的 state.rowSelection + onRowSelectionChange 模式,它依然受支持。在 Angular 中这意味着用一个 Angular signal 来拥有该状态切片,如下面的 Row Selection (Signals) 示例所示。它适合简单的集成或从 v8 迁移的场景,但粒度不如外部 atom 细。更深入的对比可参阅 Table State 指南。
readonly rowSelection = signal<RowSelectionState>({})
readonly table = injectTable(() => ({
features,
//...
onRowSelectionChange: (updater) =>
typeof updater === 'function'
? this.rowSelection.update(updater)
: this.rowSelection.set(updater),
state: {
rowSelection: this.rowSelection(),
},
}))
在 examples/angular/row-selection/src/app/app.ts 的示例中可以看到这套模式的完整落地:组件内 rowSelection signal 作为唯一数据源,onRowSelectionChange 处理函数式与值式两种 updater,并同步写回 signal;模板里通过 rowSelectionLength() 实时显示选中数量,并通过 logSelectedFlatRows() 打印 table.getSelectedRowModel().flatRows 观察选中行的完整扁平列表。
使用有业务含义的行 ID:Useful Row Ids
默认情况下,每行的行 ID 就是该行的索引(row.index)。由于行选择状态以行 ID 为键,使用行选择功能时你大概率希望行 ID 具有业务含义。此时可以用 getRowId 表格选项指定一个为每行返回唯一 ID 的函数:
readonly table = injectTable(() => ({
features,
//...
getRowId: (row) => row.uuid, // 使用数据库中该行的 uuid 作为行 ID
}))
这样当行被选中时,行选择状态将是:
{
"13e79140-62a8-4f9c-b087-5da737903b76": true,
"f3e2a5c0-5b7a-4d8a-9a5c-9c9b8a8e5f7e": false
//...
}
而不是默认的:
{
"0": true,
"1": false
//...
}
业务 ID 的价值在于:即使数据重新排序、过滤、翻页,行选择状态依然能稳定地指向同一条业务数据,不会被"行号漂移"破坏,这也是行选择状态可以包含当前 data 之外行 ID 的基础。
按条件启用行选择:Enable Row Selection Conditionally
默认情况下所有行都可被选择。若要按条件启用,或整体禁用行选择,可使用 enableRowSelection 表格选项,它既接受布尔值,也接受函数以实现更细粒度的控制:
readonly table = injectTable(() => ({
//...
enableRowSelection: row => row.original.age > 18, // 仅允许成年人所在的行被选择
}))
在 UI 层,用 row.getCanSelect() API 来强制执行某行是否可选择——无论是复选框、单选框还是其他选择控件:
readonly table = injectTable(() => ({
//...
enableRowSelection: row => row.original.age > 18,
}))
在真实示例中,examples/angular/row-selection/src/app/selection-column/selection-column.ts 的 TableRowSelection 组件正是用 [disabled]="!context.row.getCanSelect()" 来禁用不可选择行的复选框。enableRowSelection 在 rowSelectionFeature.ts 中的默认值是 true,即全量开启;传入函数时,该函数会基于每一行的上下文(含 row.original)求值。
单选模式:Single Row Selection
默认允许多行同时选中。如果只需要单选,把 enableMultiRowSelection 设为 false;或者传入函数,按行的子行情况条件性禁用多选。单选模式适合做"单选按钮"风格的表格。
readonly table = injectTable(() => ({
//...
enableMultiRowSelection: false, // 一次只允许选中一行
// enableMultiRowSelection: row => row.original.age > 18, // 仅对成年人所在行启用单选
}))
对应源码中,row_getCanMultiSelect 会同时参考 enableMultiRowSelection 与 enableRowSelection 的结果;当多选被禁用时,切换某行选择会自动先清除其它选中行,保证同一时刻至多一行处于选中状态。
父子行选择:Sub-Row Selection
默认情况下,选中父行会连带选中它的所有子行(Sub-Row)。如果你不希望自动连带选中子行,可以把 enableSubRowSelection 设为 false;同样也可以传函数按子行条件禁用。
readonly table = injectTable(() => ({
//...
enableSubRowSelection: false, // 禁用子行自动选择
// enableSubRowSelection: row => row.original.age > 18, // 对成年人子行禁用
}))
子行选择同样影响"全选"相关 API:当某个父行阻止子行选择时,table.toggleAllRowsSelected() 与 table.toggleAllPageRowsSelected() 会跳过该父行的后代;table.getIsAllRowsSelected() 与 table.getIsAllPageRowsSelected() 在判断"是否全部选中"时也会忽略这些后代。
选中一个父行时,会把父行 ID 及其可选择的子孙 ID 一并写入行选择状态。之后取消勾选某个子行,默认不会移除父行 ID——因为有些表格把状态中的 ID 视为字面意义上的"选中项"。如果你希望在取消选择子行时同时移除祖先 ID,可给切换 API 传入 deselectParents 选项:
row.getToggleSelectedHandler({ deselectParents: true })
// 或
row.toggleSelected(false, { deselectParents: true })
该选项在模板中同样可用,用于清理陈旧父行 ID,参见 expanding 示例中针对子行表格的完整模式。
Shift 范围选择:Shift Range Selection
row.getToggleSelectedHandler() 默认支持 Shift 范围选择:在一次普通的选择交互建立锚点(anchor)之后,按住 Shift 再点击另一行,会选择(或取消选择)二者之间的整个闭区间。点击复选框最终得到的勾选状态决定整个区间的结果,而被点击的端点会成为下一次 Shift 交互的新锚点。
处理函数会识别事件上的 event.shiftKey 或 event.nativeEvent.shiftKey。在 Angular 模板中,务必用 (click) 而非 (change) 绑定复选框处理函数,这样处理函数才能拿到 click 事件及其 shiftKey 修饰键。
你可以禁用范围行为,或替换事件检测逻辑:
readonly table = injectTable(() => ({
// ...
enableRowRangeSelection: false,
// 例如改用平台修饰键(Mac 的 Command)代替 Shift:
// isRowRangeSelectionEvent: event =>
// Boolean((event as { metaKey?: boolean }).metaKey),
}))
范围选择的顺序遵循表格当前的逻辑展示顺序(即过滤、分组、排序、展开之后的结果顺序)。对于客户端分页,范围可以跨越页面——因为底层使用的是完整的分页前顺序;对于手动/服务端分页,只有当前 data 中加载的行能参与范围选择。
当子行选择开启时,默认情况下范围中遇到的父行会递归地切换其可选择的子行。如果你只想改变"明确位于展示顺序区间内"的行,传入 selectChildren: false:
const handler = row.getToggleSelectedHandler({
selectChildren: false,
})
交互锚点在排序、过滤、分组、展开、分页和数据更新过程中都会被保留(只要它的行 ID 仍在展示顺序中)。如果过滤或数据替换移除了锚点,下一次 Shift 交互会退化为普通行切换,并建立新的锚点。resetRowSelection、任意"全选" API 以及 table.reset() 会清空锚点;而直接调用 row.toggleSelected()、table.setRowSelection() 以及外部受控状态变更都不会建立或移动锚点。
从源码看,锚点对应 rowSelectionFeature 初始化与重置时维护的 table._lastSelectedRowId(见 rowSelectionFeature.ts 的 initTableInstanceData/resetTableInstanceData),范围选择的具体算法可在 table-core 的 row-selection 实现 及其测试 rowSelectionRange.test.ts 中进一步研读。
渲染行选择 UI:Render Row Selection UI
TanStack Table 不规定你如何渲染选择 UI——复选框、单选框、甚至直接把点击事件绑到整行上都可以。表格实例提供了若干 API 帮助你搭建选择 UI。
把选择 API 接到复选框上
row.getToggleSelectedHandler() 可以直接绑到行复选框上,用于切换单行选择;table.getToggleAllRowsSelectedHandler() 与 table.getToggleAllPageRowsSelectedHandler 则用于"全选"复选框(前者全表,后者当前页)。这些处理函数会自动调用内部 API 更新选择状态并触发重新渲染。
如果你需要更细粒度的控制,也可以直接使用 row.toggleSelected()、table.toggleAllRowsSelected(),甚至直接用 table.setRowSelection() 像设置其他状态一样直接写入行选择状态——处理函数只是便捷封装。
<input
type="checkbox"
[checked]="table.getIsAllRowsSelected()"
[indeterminate]="table.getIsSomeRowsSelected()"
(change)="table.getToggleAllRowsSelectedHandler()?.($event)"
/>
<input
type="checkbox"
[checked]="row.getIsSelected() ||
(row.getCanSelectSubRows() && row.getIsAllSubRowsSelected())"
[disabled]="!row.getCanSelect()"
[indeterminate]="row.getIsSomeSelected()"
(click)="row.getToggleSelectedHandler()?.($event)"
/>
[!NOTE] 行复选框中的
getCanSelectSubRows()和getIsAllSubRowsSelected()两个子句只对有子行的表格有意义。扁平数据下row.getIsSelected()一个判断就够了。带子行的完整模式(含deselectParents清理)可参考 expanding 示例。
把选择 API 接到整行点击上
如果你想要更简洁的 UI,可以直接把点击事件挂到行上,row.getToggleSelectedHandler() 同样适用于这个场景:
<tbody>
@for (row of table.getRowModel().rows; track row.id) {
<tr
[class.selected]="row.getIsSelected()"
(click)="row.getToggleSelectedHandler()?.($event)"
>
@for (cell of row.getVisibleCells(); track cell.id) {
<td>
<ng-container *flexRenderCell="cell; let renderCell"
>{{ renderCell }}</ng-container
>
</td>
}
</tr>
}
</tbody>
在真实示例 examples/angular/row-selection/src/app/selection-column/selection-column.ts 中,行选择被实现为一个独立的 display 列组件:表头用 TableHeaderSelection 渲染全选复选框(getIsAllRowsSelected + getIsSomeRowsSelected + toggleAllRowsSelected),行内用 TableRowSelection 渲染行复选框(getIsSelected + getCanSelect + getToggleSelectedHandler)。该列通过 columnHelper.display({ id: 'select', ... }) 定义,位于表格第一列,示例还演示了 selectChildren: false 的传参位置。此外,示例的 app.html 展示了结合分页的完整用法:页脚用 getIsAllPageRowsSelected/getIsSomePageRowsSelected/toggleAllPageRowsSelected 提供"当前页全选"复选框。
小结
行选择是 TanStack Table Angular 版中信号友好、插件化的核心交互能力。回顾本文要点:
- 启用:通过
tableFeatures({ rowSelectionFeature })组合特性即可获得整套行选择 API; - 读状态:
table.atoms.rowSelection.get()是信号读取,模板/computed/effect中自动响应;getSelectedRowModel()系列按全量/过滤/分组维度取选中行; - 管状态:v9 推荐外部 atom 托管实现细粒度订阅;v8 风格 signal +
onRowSelectionChange依旧可用; - 稳定标识:用
getRowId换成业务 ID,让选择状态经得起排序、过滤与翻页; - 细粒度控制:
enableRowSelection、enableMultiRowSelection、enableSubRowSelection、enableRowRangeSelection分别控制按行条件启用、单选、父子行联动与 Shift 范围选择,默认值均为开启,见 rowSelectionFeature.ts 的getDefaultTableOptions; - 渲染:复选框或整行点击都可直接复用
getToggleSelectedHandler、toggleAllRowsSelected等便捷 API。
想立刻上手,可以运行仓库中的 Row Selection 示例 与 Row Selection (Signals) 示例,它们都内置了 1000 行数据、全局搜索、分页、页脚全选与选择状态实时面板,并支持一键切换 100 万行压力测试(stress test),可直接观察行选择状态在各交互下的表现;对应端到端冒烟测试位于 smoke.spec.ts。底层实现与边界行为的详细测试可继续阅读 table-core 的 row-selection 测试 与 utils 单测。