Angular TanStack Table 行选择(Row Selection)完整指南:从状态管理到多选、范围选择与父子行联动

原创2026-09-19 21:27:211,889 阅读
文章标签:前端UI组件

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 版中信号友好、插件化的核心交互能力。回顾本文要点:

  1. 启用:通过 tableFeatures({ rowSelectionFeature }) 组合特性即可获得整套行选择 API;
  2. 读状态:table.atoms.rowSelection.get() 是信号读取,模板/computed/effect 中自动响应;getSelectedRowModel() 系列按全量/过滤/分组维度取选中行;
  3. 管状态:v9 推荐外部 atom 托管实现细粒度订阅;v8 风格 signal + onRowSelectionChange 依旧可用;
  4. 稳定标识:用 getRowId 换成业务 ID,让选择状态经得起排序、过滤与翻页;
  5. 细粒度控制:enableRowSelection、enableMultiRowSelection、enableSubRowSelection、enableRowRangeSelection 分别控制按行条件启用、单选、父子行联动与 Shift 范围选择,默认值均为开启,见 rowSelectionFeature.ts 的 getDefaultTableOptions;
  6. 渲染:复选框或整行点击都可直接复用 getToggleSelectedHandler、toggleAllRowsSelected 等便捷 API。

想立刻上手,可以运行仓库中的 Row Selection 示例 与 Row Selection (Signals) 示例,它们都内置了 1000 行数据、全局搜索、分页、页脚全选与选择状态实时面板,并支持一键切换 100 万行压力测试(stress test),可直接观察行选择状态在各交互下的表现;对应端到端冒烟测试位于 smoke.spec.ts。底层实现与边界行为的详细测试可继续阅读 table-core 的 row-selection 测试 与 utils 单测。

登录后查看全文
table