TanStack Table 行选择核心接口 Row_RowSelection 全面解析从能力判定到勾选处理【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/tableTanStack Table 的 Headless 设计把行选择Row Selection能力全部收敛到Row_RowSelection接口中这一接口定义了每一行在选择功能下的完整行为契约。本文基于本仓库 table-core 源码 与配套测试逐方法剖析Row_RowSelection的 8 个成员 API——从能否选中的能力判定、到是否选中的状态查询、再到如何触发选中的勾选处理器并结合真实示例与测试用例让你彻底掌握在 React/Vue/Solid/Svelte 等框架中驱动行选择 UI 的底层机制。接口概览一份 8 方法的行选择契约Row_RowSelection定义于 rowSelectionFeature.types.ts它通过rowSelectionFeature注入到每一行的原型上见 rowSelectionFeature.ts 中的assignRowPrototype。其成员可划分为三类职责职责方法作用能力判定getCanMultiSelect()/getCanSelect()/getCanSelectSubRows()判断行是否可选中、可否与其他行同时选中、选中时是否级联子行状态查询getIsSelected()/getIsSomeSelected()/getIsAllSubRowsSelected()查询行本身、部分子行、全部子行的选中状态驱动复选框的 checked / indeterminate 三态状态变更toggleSelected()/getToggleSelectedHandler()以命令式或事件驱动的方式切换行的选中状态在进入各方法细节前先明确行选择的状态载体RowSelectionState是一个Recordstring, true映射源码定义以行 id 为键、true为值行 id 不存在于映射中即视为未选中对应isRowSelected中hasOwn与真值双重判断见 rowSelectionFeature.utils.ts。行选择默认开启enableRowSelection: true并支持三个全局开关enableRowSelection、enableMultiRowSelection、enableSubRowSelection三者均可传布尔值或逐行判定函数默认值配置。能力判定三兄弟getCanSelect / getCanMultiSelect / getCanSelectSubRows这三个方法负责回答这一行在选择体系中处于什么位置是渲染复选框disabled状态的依据。getCanSelect()这一行能否被选中getCanSelect: () boolean其实现row_getCanSelectrowSelectionFeature.utils.ts直接读取options.enableRowSelection若为函数则调用options.enableRowSelection(row)逐行判定否则返回布尔值本身默认true。典型场景如下方示例所示enableRowSelection: true, // 全部行可选 // enableRowSelection: row row.original.age 18, // 按行条件启用当某行不可选时示例代码会用disabled{!row.getCanSelect()}禁用其复选框见 row-selection 示例。getCanMultiSelect()能否与其他行同时选中getCanMultiSelect: () boolean对应row_getCanMultiSelectutils 第 670-680 行读取options.enableMultiRowSelection同样支持布尔或逐行谓词默认true。该方法是单选模式的裁决者当返回false时mutateRowIsSelected会在选中该行前清空整个选择映射utils 第 817-820 行从而实现单选框行为。同时它也是 Shift 范围选择的重要门槛——范围选择要求锚点行与当前行都满足getCanMultiSelect()否则回退为普通切换详见后文。getCanSelectSubRows()选中父行是否级联子行getCanSelectSubRows: () boolean对应row_getCanSelectSubRowsutils 第 647-657 行读取options.enableSubRowSelection默认true。它控制选中父行时是否递归选中其 subRows在分组grouping与展开expanding场景下尤为重要。选择全选select-all时isRowSelectableInSelectAll会沿祖先链向上检查任一祖先阻止子行选择enableSubRowSelection谓词返回false则其整棵子树都会被跳过utils 第 850-889 行并借助subtreeCache缓存每个祖先的判定结果避免兄弟行共享祖先链时的重复遍历。状态查询三方法getIsSelected / getIsSomeSelected / getIsAllSubRowsSelected这三个方法分别回答是否选中是否部分选中是否全部子行选中恰好对应复选框的checked、indeterminate、checked父行三态展示。getIsSelected()本行是否被选中getIsSelected: () boolean实现row_getIsSelected通过isRowSelected(row, rowSelection)判断utils 第 571-577 行从row.table.atoms.rowSelection读取选择映射行 id 存在且值为true即为选中缺失则视为未选中。它被用作示例中行复选框的checked{row.getIsSelected()}示例。getIsSomeSelected()是否有部分可选中后代被选中getIsSomeSelected: () boolean对应row_getIsSomeSelectedutils 第 589-594 行返回isSubRowSelected(row) some。isSubRowSelected递归遍历子孙行返回boolean | some | all三态utils 第 1013-1062 行没有任何可选中后代时返回false后代全部选中返回all部分选中返回some。它驱动父行复选框的 indeterminate 视觉态示例中indeterminate{row.getIsSomeSelected()}即由此而来。getIsAllSubRowsSelected()所有可选中后代是否全部选中getIsAllSubRowsSelected: () boolean对应row_getIsAllSubRowsSelectedutils 第 606-611 行返回isSubRowSelected(row) all。与getIsSomeSelected共享同一套三态计算一个用于部分一个用于全部。注意无子行或无可选中后代的行一律返回false不会误报全选。从源码结构看这两个方法在 rowSelectionFeature.ts 的注册中都声明了 memo 依赖row.subRows、rowSelection原子、enableRowSelection意味着其计算结果是响应式缓存的子行结构或选择状态变化时才会重算。状态变更双通道toggleSelected 与 getToggleSelectedHandler如果说查询方法负责读这两个方法负责写且都接受 ToggleSelectedOptions 控制级联行为选项类型默认值含义selectChildrenbooleantrue是否递归切换可选中子行deselectParentsbooleanfalse取消选中时是否同时从选择映射中删除祖先行 id用于清理父级级联写入的过期父 idtoggleSelected(value?, opts?)命令式切换toggleSelected: (value?, opts?) void对应row_toggleSelectedutils 第 534-559 行。核心行为省略value时基于当前选中态取反value !isSelected子行递归受(opts?.selectChildren ?? true) row_getCanMultiSelect(row)双重约束——注意单选行不会级联子行值为false且传入deselectParents: true时调用pruneAncestorRowIds沿parentId链向上删除所有祖先 idutils 第 891-907 行。该清理不受enableRowSelection门控——即使祖先本身不可交互选中也会被清理避免子行已取消但父行仍显示选中的脏状态。示例中的用法覆盖了各种形态table.getRow(parent).toggleSelected(true) // 级联选中子孙 row.toggleSelected(true, { selectChildren: false }) // 只选本行 row.toggleSelected(false, { deselectParents: true }) // 取消选中并清理祖先getToggleSelectedHandler(opts?)复选框专用事件处理器getToggleSelectedHandler: (opts?) (event) void这是接口中签名最复杂的方法返回一个checkbox 风格的事件处理器utils 第 697-727 行。它的特殊之处在于支持 Shift 范围选择文档明确要求传入原生复选框点击事件或nativeEvent为该点击的框架包装事件以便处理器读取修饰键。其执行流程行不可选时直接返回no-op读取event.target.checked作为目标选中值判断是否构成范围选择enableRowRangeSelection ! false且存在锚点行table._lastSelectedRowId非空且当前行可多选且isRowRangeSelectionEvent(e)判定为真若满足范围条件则走selectRowRange批量切换否则回退到row_toggleSelected无论走哪条路径最后都会把当前行 id 写入table._lastSelectedRowId作为下一次范围选择的锚点。默认的isRowRangeSelectionEvent检查event.shiftKey || event.nativeEvent?.shiftKey默认配置即 Shift 键触发范围选择你也可以自定义例如改用 Meta 键isRowRangeSelectionEvent: event Boolean(event.metaKey)示例中有注释演示见 main.tsx。通过enableRowRangeSelection: false可整体关闭范围选择。范围选择的底层原理锚点 显示顺序区间selectRowRangeutils 第 740-802 行实现了范围选择的完整语义是理解getToggleSelectedHandler的关键锚点解析从分页前行模型getPrePaginatedRowModel优先解析锚点找不到再回退核心行模型锚点不存在如已被过滤移除则返回false触发普通切换回退。区间计算基于getRowsInDisplayOrder()的最新显示顺序取锚点与当前行显示索引的闭区间[start, end]。这意味着范围选择跟随当前的排序、过滤、分组、展开与分页管线——测试用例验证了排序变更、列过滤、分组行、跨页选择等场景见 rowSelectionRange.test.ts。批量应用区间内每行若getCanSelect()且getCanMultiSelect()才被切换区间外的既有选择不受影响整个区间通过一次table_setRowSelection更新完成而非逐行调用toggleSelected。测试断言onRowSelectionChange仅被调用一次且toggleSelected完全未被调用测试第 220-238 行这是范围选择的高性能保证。子行语义默认selectChildren: true区间内行的折叠子行也会被递归选中传selectChildren: false则仅影响显示区间内明确出现的行测试第 311-331 行。锚点生命周期也有严格约定普通点击非范围同样更新锚点但toggleSelected、setRowSelection等直接 API 不会触碰锚点resetRowSelection、toggleAllRowsSelected、toggleAllPageRowsSelected及全局reset都会清空锚点测试第 485-517 行。与表格级 API 的联动从单行到全选Row_RowSelection并非孤立存在它与Table_RowSelection同文件第 129-211 行协同工作。表头复选框通常组合使用表格级 APIchecked{table.getIsAllRowsSelected()} // 全表是否全选 indeterminate{table.getIsSomeRowsSelected()} // 是否有行被选中 onChange{table.getToggleAllRowsSelectedHandler()} // 全选/全不选处理器页脚则可使用getIsAllPageRowsSelected/getIsSomePageRowsSelected/getToggleAllPageRowsSelectedHandler控制当前页全选见 示例。选中结果通过table.getSelectedRowModel()等派生模型消费其内部由selectRowsFn递归收集选中行utils 第 909-986 行测试还验证了未选中父行下的已选子行仍会进入 flatRows以及克隆行保留原型链以便getValue()可用等细节rowSelectionFeature.test.ts。小结Row_RowSelection是 TanStack Table 行选择功能的单行级契约三个能力判定方法getCanSelect、getCanMultiSelect、getCanSelectSubRows对应三个enable*配置项及其逐行谓词形态三个状态查询方法getIsSelected、getIsSomeSelected、getIsAllSubRowsSelected围绕Recordstring, true选择映射与三态子行计算展开toggleSelected与getToggleSelectedHandler则分别提供命令式与事件驱动的切换通道后者还内建了基于锚点、跟随显示管线的 Shift 范围选择。理解这 8 个方法你就能在任意支持 TanStack Table 的框架中写出符合平台习惯的、具备三态复选框与范围选择能力的行选择 UI。深入阅读 rowSelectionFeature.utils.ts 与 范围选择测试可进一步掌握其边界语义与性能优化细节。【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/21 20:29:12 · 阅读 1.2k TanStack Table 行选择核心接口 Row_RowSelection 全面解析：从能力判定到勾选处理
TanStack Table 行选择核心接口 Row_RowSelection 全面解析从能力判定到勾选处理【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/tableTanStack Table 的 Headless 设计把行选择Row Selection能力全部收敛到Row_RowSelection接口中这一接口定义了每一行在选择功能下的完整行为契约。本文基于本仓库 table-core 源码 与配套测试逐方法剖析Row_RowSelection的 8 个成员 API——从能否选中的能力判定、到是否选中的状态查询、再到如何触发选中的勾选处理器并结合真实示例与测试用例让你彻底掌握在 React/Vue/Solid/Svelte 等框架中驱动行选择 UI 的底层机制。接口概览一份 8 方法的行选择契约Row_RowSelection定义于 rowSelectionFeature.types.ts它通过rowSelectionFeature注入到每一行的原型上见 rowSelectionFeature.ts 中的assignRowPrototype。其成员可划分为三类职责职责方法作用能力判定getCanMultiSelect()/getCanSelect()/getCanSelectSubRows()判断行是否可选中、可否与其他行同时选中、选中时是否级联子行状态查询getIsSelected()/getIsSomeSelected()/getIsAllSubRowsSelected()查询行本身、部分子行、全部子行的选中状态驱动复选框的 checked / indeterminate 三态状态变更toggleSelected()/getToggleSelectedHandler()以命令式或事件驱动的方式切换行的选中状态在进入各方法细节前先明确行选择的状态载体RowSelectionState是一个Recordstring, true映射源码定义以行 id 为键、true为值行 id 不存在于映射中即视为未选中对应isRowSelected中hasOwn与真值双重判断见 rowSelectionFeature.utils.ts。行选择默认开启enableRowSelection: true并支持三个全局开关enableRowSelection、enableMultiRowSelection、enableSubRowSelection三者均可传布尔值或逐行判定函数默认值配置。能力判定三兄弟getCanSelect / getCanMultiSelect / getCanSelectSubRows这三个方法负责回答这一行在选择体系中处于什么位置是渲染复选框disabled状态的依据。getCanSelect()这一行能否被选中getCanSelect: () boolean其实现row_getCanSelectrowSelectionFeature.utils.ts直接读取options.enableRowSelection若为函数则调用options.enableRowSelection(row)逐行判定否则返回布尔值本身默认true。典型场景如下方示例所示enableRowSelection: true, // 全部行可选 // enableRowSelection: row row.original.age 18, // 按行条件启用当某行不可选时示例代码会用disabled{!row.getCanSelect()}禁用其复选框见 row-selection 示例。getCanMultiSelect()能否与其他行同时选中getCanMultiSelect: () boolean对应row_getCanMultiSelectutils 第 670-680 行读取options.enableMultiRowSelection同样支持布尔或逐行谓词默认true。该方法是单选模式的裁决者当返回false时mutateRowIsSelected会在选中该行前清空整个选择映射utils 第 817-820 行从而实现单选框行为。同时它也是 Shift 范围选择的重要门槛——范围选择要求锚点行与当前行都满足getCanMultiSelect()否则回退为普通切换详见后文。getCanSelectSubRows()选中父行是否级联子行getCanSelectSubRows: () boolean对应row_getCanSelectSubRowsutils 第 647-657 行读取options.enableSubRowSelection默认true。它控制选中父行时是否递归选中其 subRows在分组grouping与展开expanding场景下尤为重要。选择全选select-all时isRowSelectableInSelectAll会沿祖先链向上检查任一祖先阻止子行选择enableSubRowSelection谓词返回false则其整棵子树都会被跳过utils 第 850-889 行并借助subtreeCache缓存每个祖先的判定结果避免兄弟行共享祖先链时的重复遍历。状态查询三方法getIsSelected / getIsSomeSelected / getIsAllSubRowsSelected这三个方法分别回答是否选中是否部分选中是否全部子行选中恰好对应复选框的checked、indeterminate、checked父行三态展示。getIsSelected()本行是否被选中getIsSelected: () boolean实现row_getIsSelected通过isRowSelected(row, rowSelection)判断utils 第 571-577 行从row.table.atoms.rowSelection读取选择映射行 id 存在且值为true即为选中缺失则视为未选中。它被用作示例中行复选框的checked{row.getIsSelected()}示例。getIsSomeSelected()是否有部分可选中后代被选中getIsSomeSelected: () boolean对应row_getIsSomeSelectedutils 第 589-594 行返回isSubRowSelected(row) some。isSubRowSelected递归遍历子孙行返回boolean | some | all三态utils 第 1013-1062 行没有任何可选中后代时返回false后代全部选中返回all部分选中返回some。它驱动父行复选框的 indeterminate 视觉态示例中indeterminate{row.getIsSomeSelected()}即由此而来。getIsAllSubRowsSelected()所有可选中后代是否全部选中getIsAllSubRowsSelected: () boolean对应row_getIsAllSubRowsSelectedutils 第 606-611 行返回isSubRowSelected(row) all。与getIsSomeSelected共享同一套三态计算一个用于部分一个用于全部。注意无子行或无可选中后代的行一律返回false不会误报全选。从源码结构看这两个方法在 rowSelectionFeature.ts 的注册中都声明了 memo 依赖row.subRows、rowSelection原子、enableRowSelection意味着其计算结果是响应式缓存的子行结构或选择状态变化时才会重算。状态变更双通道toggleSelected 与 getToggleSelectedHandler如果说查询方法负责读这两个方法负责写且都接受 ToggleSelectedOptions 控制级联行为选项类型默认值含义selectChildrenbooleantrue是否递归切换可选中子行deselectParentsbooleanfalse取消选中时是否同时从选择映射中删除祖先行 id用于清理父级级联写入的过期父 idtoggleSelected(value?, opts?)命令式切换toggleSelected: (value?, opts?) void对应row_toggleSelectedutils 第 534-559 行。核心行为省略value时基于当前选中态取反value !isSelected子行递归受(opts?.selectChildren ?? true) row_getCanMultiSelect(row)双重约束——注意单选行不会级联子行值为false且传入deselectParents: true时调用pruneAncestorRowIds沿parentId链向上删除所有祖先 idutils 第 891-907 行。该清理不受enableRowSelection门控——即使祖先本身不可交互选中也会被清理避免子行已取消但父行仍显示选中的脏状态。示例中的用法覆盖了各种形态table.getRow(parent).toggleSelected(true) // 级联选中子孙 row.toggleSelected(true, { selectChildren: false }) // 只选本行 row.toggleSelected(false, { deselectParents: true }) // 取消选中并清理祖先getToggleSelectedHandler(opts?)复选框专用事件处理器getToggleSelectedHandler: (opts?) (event) void这是接口中签名最复杂的方法返回一个checkbox 风格的事件处理器utils 第 697-727 行。它的特殊之处在于支持 Shift 范围选择文档明确要求传入原生复选框点击事件或nativeEvent为该点击的框架包装事件以便处理器读取修饰键。其执行流程行不可选时直接返回no-op读取event.target.checked作为目标选中值判断是否构成范围选择enableRowRangeSelection ! false且存在锚点行table._lastSelectedRowId非空且当前行可多选且isRowRangeSelectionEvent(e)判定为真若满足范围条件则走selectRowRange批量切换否则回退到row_toggleSelected无论走哪条路径最后都会把当前行 id 写入table._lastSelectedRowId作为下一次范围选择的锚点。默认的isRowRangeSelectionEvent检查event.shiftKey || event.nativeEvent?.shiftKey默认配置即 Shift 键触发范围选择你也可以自定义例如改用 Meta 键isRowRangeSelectionEvent: event Boolean(event.metaKey)示例中有注释演示见 main.tsx。通过enableRowRangeSelection: false可整体关闭范围选择。范围选择的底层原理锚点 显示顺序区间selectRowRangeutils 第 740-802 行实现了范围选择的完整语义是理解getToggleSelectedHandler的关键锚点解析从分页前行模型getPrePaginatedRowModel优先解析锚点找不到再回退核心行模型锚点不存在如已被过滤移除则返回false触发普通切换回退。区间计算基于getRowsInDisplayOrder()的最新显示顺序取锚点与当前行显示索引的闭区间[start, end]。这意味着范围选择跟随当前的排序、过滤、分组、展开与分页管线——测试用例验证了排序变更、列过滤、分组行、跨页选择等场景见 rowSelectionRange.test.ts。批量应用区间内每行若getCanSelect()且getCanMultiSelect()才被切换区间外的既有选择不受影响整个区间通过一次table_setRowSelection更新完成而非逐行调用toggleSelected。测试断言onRowSelectionChange仅被调用一次且toggleSelected完全未被调用测试第 220-238 行这是范围选择的高性能保证。子行语义默认selectChildren: true区间内行的折叠子行也会被递归选中传selectChildren: false则仅影响显示区间内明确出现的行测试第 311-331 行。锚点生命周期也有严格约定普通点击非范围同样更新锚点但toggleSelected、setRowSelection等直接 API 不会触碰锚点resetRowSelection、toggleAllRowsSelected、toggleAllPageRowsSelected及全局reset都会清空锚点测试第 485-517 行。与表格级 API 的联动从单行到全选Row_RowSelection并非孤立存在它与Table_RowSelection同文件第 129-211 行协同工作。表头复选框通常组合使用表格级 APIchecked{table.getIsAllRowsSelected()} // 全表是否全选 indeterminate{table.getIsSomeRowsSelected()} // 是否有行被选中 onChange{table.getToggleAllRowsSelectedHandler()} // 全选/全不选处理器页脚则可使用getIsAllPageRowsSelected/getIsSomePageRowsSelected/getToggleAllPageRowsSelectedHandler控制当前页全选见 示例。选中结果通过table.getSelectedRowModel()等派生模型消费其内部由selectRowsFn递归收集选中行utils 第 909-986 行测试还验证了未选中父行下的已选子行仍会进入 flatRows以及克隆行保留原型链以便getValue()可用等细节rowSelectionFeature.test.ts。小结Row_RowSelection是 TanStack Table 行选择功能的单行级契约三个能力判定方法getCanSelect、getCanMultiSelect、getCanSelectSubRows对应三个enable*配置项及其逐行谓词形态三个状态查询方法getIsSelected、getIsSomeSelected、getIsAllSubRowsSelected围绕Recordstring, true选择映射与三态子行计算展开toggleSelected与getToggleSelectedHandler则分别提供命令式与事件驱动的切换通道后者还内建了基于锚点、跟随显示管线的 Shift 范围选择。理解这 8 个方法你就能在任意支持 TanStack Table 的框架中写出符合平台习惯的、具备三态复选框与范围选择能力的行选择 UI。深入阅读 rowSelectionFeature.utils.ts 与 范围选择测试可进一步掌握其边界语义与性能优化细节。【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考