TanStack Svelte Table 单元格选择Cell Selection完全指南从拖拽选区到剪贴板导出【免费下载链接】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导读本文基于 TanStack Table 官方 Svelte 指南与当前仓库源码系统讲解cellSelectionFeature单元格选择特性的完整用法如何启用该特性、理解其基于锚点/焦点角的区间操作状态模型、绑定鼠标拖拽与 Shift/Ctrl 扩展交互、用 roving tabindex 与选中边框渲染选区 UI、通过 TanStack Hotkeys 实现键盘导航以及把选区安全地复制为表格数据。读完本文你将能在 Svelte 5 项目中构建出类似电子表格的单元格选择体验并理解选择状态为何能在排序、过滤、固定列与分页之后依然保持正确。本文对应的官方指南原文位于 docs/framework/svelte/guide/cell-selection.md完整可运行示例位于 examples/svelte/cell-selection其核心渲染逻辑见 App.svelte。先看示例一个完整的单元格选择表格仓库中的 cell-selection 示例 是一个开箱即用的 Svelte 5 项目演示了本文要讲的全部能力。示例的 package.json 给出了运行环境tanstack/svelte-tablev9当前示例锁定的版本为^9.1.2tanstack/svelte-hotkeysv0.10用于键盘导航Svelte 5^5.56.8—— 本文所有响应式代码都基于 runes 语法Vite 作为开发服务器在该目录下执行npm install后运行npm run dev即可启动示例还带有 Playwright 端到端测试npm run test:e2e其中 smoke.spec.ts 通过真实浏览器交互验证了Shift-click 选中 3×3 矩形、锚点单元格保持cell-focused等行为可作为验收标准参考。启用单元格选择特性单元格选择Cell Selection是 TanStack Table 的可选特性feature通过组合tableFeatures注入表格。以下代码来自 App.svelte 的简化版本import { createTable, tableFeatures, cellSelectionFeature, } from tanstack/svelte-table const features tableFeatures({ cellSelectionFeature }) const table createTable({ features, columns, get data() { return data }, })关键点tableFeatures({ cellSelectionFeature })会注册该特性提供的全部表格 API、单元格原型方法以及默认选项特性注册后cellSelection状态切片、table.getSelectedCellCount()等一系列 API 即刻可用特性是可选组合的你可以把它与排序、列固定、列排序等特性并列注册示例中即同时启用了columnOrderingFeature、columnPinningFeature、columnVisibilityFeature与rowSortingFeature。从源码看特性在注册时通过getDefaultTableOptions写入了一系列默认选项见 cellSelectionFeature.ts选项默认值作用enableCellSelectiontrue是否允许选择单元格可传函数做逐单元格判断enableCellRangeSelectiontrue是否允许拖拽与 Shift 扩展的矩形范围选择enableMultiCellRangeSelectiontrue是否允许 Ctrl/Cmd 追加或排除多个矩形enableCellSelectionDragtrue是否允许拖拽即选中为false时只能单击onCellSelectionChange内部 updater选择状态变化的回调用于受控模式autoResetCellSelectiontruedata变化时是否自动重置选择此外特性默认的isCellRangeSelectionEvent同时识别event.shiftKey与event.nativeEvent.shiftKeyisMultiCellRangeSelectionEvent则识别ctrlKey/metaKey及对应的nativeEvent字段以保证跨框架事件对象兼容。读取选择状态启用特性后表格实例自动托管选择状态你可以通过一组 API 读取它table.atoms.cellSelection.get()—— 返回当前选择状态在模板或 rune 中读取时参与 Svelte 的细粒度依赖追踪table.getSelectedCellCount()—— 返回选中单元格总数table.getSelectedCellIds()—— 返回所有选中单元格的 id形如rowId_columnIdtable.getCellSelectionRowIds()/table.getCellSelectionColumnIds()—— 返回选区所触及的行与列table.getSelectedCellRangesData()—— 返回每个最终正向选区的值按行主序的二维网格组织。console.log(table.atoms.cellSelection.get()) // 当前选择状态 console.log(table.getSelectedCellCount()) // 3 console.log(table.getSelectedCellIds()) // [0_firstName, 0_lastName, 1_firstName] console.log(table.getSelectedCellRangesData()) // [[[Tanner, Linsley], [Kevin, Vandy]]]在 Svelte 模板或 rune 中读取同一个 atom即可获得声明式响应const cellSelection $derived(table.atoms.cellSelection.get()) const selectedRangeCount $derived(cellSelection.length)在非追踪上下文如普通事件回调中table.atoms.cellSelection.get()就是一个普通快照。需要特别说明的是性能设计getSelectedCellIds、getSelectedCellRangesData等展开类API 是**记忆化memoized且按需计算pull-based**的。从 cellSelectionFeature.ts 可以看到它们的memoDeps指向getCellSelectionBounds等缓存结果只有真正被调用才会付出枚举成本。因此一个只做高亮展示的表格永远不会为一个超大规模选区付出枚举开销。选择状态的数据结构CellSelectionState是一组有序的区间操作range operations每个操作只记录定义矩形的两个对角type CellSelectionRange { anchorRowId: string anchorColumnId: string focusRowId: string focusColumnId: string operation?: include | exclude } type CellSelectionState ArrayCellSelectionRange理解这对锚点/焦点语义是掌握本特性的关键anchor锚点选区开始的那个角位置固定不动focus焦点拖拽或 Shift 扩展时移动的那个角。源码刻意不把矩形规范化为 min/max 形式而是保留两个原始角——cellSelectionFeature.utils.ts 中的table_getCellSelectionBounds在真正需要时才把它们解析为显示顺序下的索引矩形。这样做正是为了支持Shift 扩展和回缩到活动单元格只要焦点角还能动锚点不变选区就能持续扩展或收缩。区间按顺序应用省略operation表示包含include向后兼容exclude区间从当前已产生的选区内减去其矩形。这种操作日志式设计意味着全选但排除某些单元格这类交互不需要为每个选中单元格建一条记录——只需一条 include 加若干条 exclude。矩形代数求交、相减、合并实现在 cellSelectionGeometry.ts并有对应的单元测试cellSelectionGeometry.test.ts保证正确性。管理选择状态受控与外部 atom如果选择状态需要被应用的其他部分访问例如存入持久化存储你可以自己持有这个状态切片。v9 推荐的方式是把外部 atom通过atoms选项传入import { createAtom } from tanstack/svelte-store import { createTable, tableFeatures, cellSelectionFeature, type CellSelectionState, } from tanstack/svelte-table const features tableFeatures({ cellSelectionFeature }) const cellSelectionAtom createAtomCellSelectionState([]) const table createTable({ features, columns, get data() { return data }, atoms: { cellSelection: cellSelectionAtom }, })经典的受控状态模式同样可用与onCellSelectionChange配对let cellSelection $stateCellSelectionState([]) const table createTable({ features, columns, get data() { return data }, get state() { return { cellSelection } }, onCellSelectionChange: (updater) { cellSelection updater instanceof Function ? updater(cellSelection) : updater }, })[!NOTE]注意一次拖拽中指针每跨越一个单元格边界就会触发一次变更因此onCellSelectionChange在拖拽期间会高频触发。如果要把选区同步到服务器或 URL请做防抖debounce或只在mouseup时统一提交。行 id 的选择很重要单元格选择以row id column id作为键因此getRowId的意义与行选择row selection完全一致要用数据中稳定不变的字段作为行 id而不是依赖渲染位置。const table createTable({ features, //... getRowId: (row) row.uuid, // 用数据库中的 uuid 作为行 id })示例代码中getRowId: (row: Person) row.id即此用法见 App.svelte。区间记录的是 id 而非位置这直接决定了后文选区如何跨越表格变化一节中那些优雅行为的底层原因。按条件启用单元格选择默认情况下每个单元格都可被选择。用表格级enableCellSelection可以整体关闭或传入函数实现逐单元格控制const table createTable({ features, //... enableCellSelection: (cell) cell.row.original.age 18, // 仅成年人的单元格可选中 })列定义也可以单独退出选择——这是复选框列、操作列等场景的常见需求。列级false优先于表格级选项columnHelper.accessor(actions, { enableCellSelection: false, // 该列永远不可选中 })这一优先级逻辑在 cellSelectionFeature.utils.ts 的cell_getCanSelect中实现先查列定义再回落到表格选项。不可选中的单元格即使被矩形穿过也会被跳过键盘导航的moveCellSelection会跨过该列而不是停在上面。渲染时请用cell.getCanSelect()决定是否挂接选择事件处理器——示例的 App.svelte 中{#if cell.getCanSelect()}分支正是这样做的。鼠标交互所有鼠标交互都由两个单元格处理器驱动cell.getSelectionStartHandler()—— 绑定到onMouseDown开始/修改选区cell.getSelectionExtendHandler()—— 绑定到onMouseEnter拖拽经过时移动焦点角。td onmousedown{cell.getSelectionStartHandler()} onmouseenter{cell.getSelectionExtendHandler()} FlexRender {cell} / /td你不需要自己处理mouseupstart handler 内部会挂接 document 级的mouseup监听器并在拖拽结束时移除所以即使指针在表格外松开拖拽也能正确收尾。如果表格渲染在另一个 document如 iframe 或弹出窗口中把该 document 传进去即可cell.getSelectionStartHandler(myDocument)。拖拽选择Drag Selection按下单元格会开启一个新的单单元格区间之后指针经过的每个单元格都会移动该区间的焦点角。设enableCellSelectionDrag: false可以改为只响应显式点击。Shift 范围选择Range SelectionShift 点击会把当前活动区间的焦点角移动到被点单元格锚点保持不动因此活动单元格始终停留在选区起点——这正是电子表格的行为。处理器同时识别event.shiftKey与event.nativeEvent.shiftKey。你可以关闭范围行为或替换其判定逻辑const table createTable({ features, //... enableCellRangeSelection: false, // 例如改用平台修饰键而不是 Shift // isCellRangeSelectionEvent: event Boolean(event.metaKey), })多范围选择Multiple RangesCtrl/Cmd 点击未选中单元格追加一个新的包含include矩形Ctrl/Cmd 点击已选中单元格改为追加一个排除exclude操作——点击移除该单元格拖拽则减去整个矩形一次拖拽是包含还是排除在开始时即确定收缩排除型拖拽会把重新暴露的单元格加回来设enableMultiCellRangeSelection: false可同时禁用两种行为或用isMultiCellRangeSelectionEvent更换修饰键判定。编程式区间操作table.selectCellRange(range) // 替换当前选区 table.selectCellRange(range, { mode: include }) // 追加包含 table.selectCellRange(range, { mode: exclude }) // 追加排除旧的{ additive: true }是 include 模式的弃用别名若两个选项同时提供mode优先。底层实现见 cellSelectionFeature.utils.tsreplace模式会清空旧区间[nextRange]include/exclude则追加到日志尾部。table.getCellSelectionBounds()则把整条操作日志解析为互不相交、确定性的正向矩形集合——这是所有渲染与枚举 API 的公共底层缓存。渲染选区 UITanStack Table 不规定选中单元格如何渲染下面这些单元格 API 提供了你需要的一切cell.getIsSelected()—— 该单元格是否落在任一区间内cell.getIsFocused()—— 是否为活动单元格被排除的锚点可以是聚焦但未选中cell.getSelectionEdges()—— 哪些边位于选区边界上cell.getTabIndex()—— 聚焦单元格返回0其余返回-1用于 roving tabindex。getSelectionEdges()返回{ top, right, bottom, left }某一边为true表示该方向上的相邻单元格未被选中。这正是绘制连续外轮廓的关键即使选区是多个矩形的并集也能画出一条完整连续的外框线而无需每个单元格去逐个检查邻居。示例中的getCellClassNameApp.svelte演示了完整用法function getCellClassName(cell) { // 大多数单元格未选中先快速退出避免无谓地解析边缘 if (!cell.getIsSelected()) { return cell.getIsFocused() ? cell cell-focused : cell } const edges cell.getSelectionEdges() return [ cell, cell-selected, cell.getIsFocused() cell-focused, edges.top cell-edge-top, edges.right cell-edge-right, edges.bottom cell-edge-bottom, edges.left cell-edge-left, ] .filter(Boolean) .join( ) }[!TIP] 绘制轮廓请用box-shadow: inset ...而非border。在border-collapse的表格上加粗的 border 会撑宽共享的网格线导致单元格被选中时行高发生变化而 box-shadow 不影响布局。示例的 index.css 即采用该方案。键盘导航单元格选择特性本身不内置任何键盘处理而是暴露一组命令式 API交给专门的快捷键库如 TanStack Hotkeys驱动table.moveCellSelection(direction)—— 把选区收缩到朝某方向一步之遥的单个单元格table.extendCellSelection(direction)—— 移动活动区间的焦点角锚点不变table.setFocusedCell(rowId, columnId)—— 把选区收缩到指定单元格table.selectAllCells()—— 选中所有可选中单元格table.resetCellSelection(true)—— 清空选区。direction取up、down、left、right。从源码看moveCellSelection/extendCellSelection的导航步进cellSelectionFeature.utils.ts约束在最终行模型内、会跳过不可选中的列防止方向键把焦点移入未渲染的页面或不可选中的列。结合 TanStack Hotkeys 的完整绑定与 App.svelte 一致import { createHotkeysAttachment } from tanstack/svelte-hotkeys const gridKeys createHotkeysAttachment([ { hotkey: ArrowUp, callback: () table.moveCellSelection(up) }, { hotkey: ArrowDown, callback: () table.moveCellSelection(down) }, { hotkey: ShiftArrowDown, callback: () table.extendCellSelection(down), }, { hotkey: ModA, callback: () table.selectAllCells() }, { hotkey: Escape, callback: () table.resetCellSelection(true) }, ]) // 然后在模板中 // div tabindex0 {attach gridKeys} ... /div务必把快捷键作用域限定在网格元素而不是 document 上否则方向键和 Escape 会劫持页面上其他输入框的按键。示例中table tabindex0 {attach gridKeys}App.svelte正是把焦点圈定在网格内示例还把粘贴测试用的textarea放在网格元素之外避免快捷键干扰输入。把选区复制为表格数据getSelectedCellRangesData()返回原始值索引结构为[regionIndex][rowIndex][columnIndex]。注意一个 region 是最终应用完所有 include/exclude 运算后的互不相交正向矩形因此与存储状态并不一一对应。把它转成剪贴板文本属于应用层职责——分隔符、null的表示、引号规则都只能由你决定。示例App.svelte实现了一个电子表格风格的 TSV 序列化function escapeTsvValue(value: unknown) { const text value null ? : String(value) const safeText typeof value string /^[\t\r ]*[-]/.test(value) ? ${text} // 防公式注入以 - 开头的值前置单引号 : text // 电子表格约定字段含分隔符、换行或引号时必须加引号内部引号翻倍 return /[\t\n\r]/.test(safeText) ? ${safeText.replace(//g, )} : safeText } function toTsv(ranges: ArrayArrayArrayunknown) { return ranges .map((grid) grid.map((row) row.map(escapeTsvValue).join(\t)).join(\n), ) .join(\n\n) // 各最终选区之间以空行分隔 } navigator.clipboard.writeText(toTsv(table.getSelectedCellRangesData()))值得注意escapeTsvValue中的公式注入防护/^[\t\r ]*[-]/匹配以等号、加号、、减号开头可带前导空白的字符串并前置单引号——这是从表格复制到电子表格类应用时的常见安全实践。选区如何跨越表格变化而存活区间存储的是row id 与 column id 而非屏幕坐标因此它们跟随各自的角单元格而不是跟随屏幕位置排序、过滤、列重排角点保持固定系统重算两角之间的内容。例如从行 A 到行 B的区间排序后仍然覆盖行 A 到行 B即使中间的行已完全不同。列固定pinning选区按渲染顺序先 start 固定列、再中间、最后 end 固定列建立索引。table_getCellSelectionColumnIndexes中的getDisplayOrderedColumnscellSelectionFeature.utils.ts专门处理了这一顺序保证固定列时矩形在视觉上仍然连续而不是在索引空间连续、画面上却破碎。隐藏角所在的列该区间失效——不渲染任何选中态但状态仍保留重新显示该列时自动恢复。分页区间针对分页前的顺序解析因此可以跨页存在并在你查看的任一页上正确点亮。由于列重排可能把选区拓宽到用户从未主动选择的列上一些应用倾向于在列布局变化时清空选区——这是应用层决策。一个 Svelte$effect即可实现参考 App.svelte它额外监听了排序并用untrack包裹写入let isFirstColumnLayout true $effect(() { // 只读取布局相关 atom。若读 table.store.get() 会因任何状态变化包括 // 选区变化本身而重跑形成死循环。 void table.atoms.columnOrder.get() void table.atoms.columnPinning.get() void table.atoms.columnVisibility.get() if (isFirstColumnLayout) { isFirstColumnLayout false return } table.resetCellSelection(true) })示例仓库的 e2e 测试 smoke.spec.ts 专门验证了反转列序、固定列、隐藏列、排序这一系列布局变更后页面不报错、不进入响应式死循环可作为该模式正确性的参考。重置选择table.resetCellSelection()恢复initialState.cellSelection传true则忽略初始状态、彻底清空源码见table_resetCellSelectioncellSelectionFeature.utils.ts。选择还会在data变化时自动重置因为新数据可能使区间指向的 row id 失效或在 id 被复用的情况下静默重新选中某些单元格。用autoResetCellSelection: false关闭注意autoResetAll优先级更高const table createTable({ features, //... autoResetCellSelection: false, // 在数据变化时保留区间 })性能要点Svelte 的 runes 会追踪 atom 读取编译器只更新真正变化的 DOM 节点因此示例可以朴素地渲染每个单元格——不需要 React 那种逐行 Subscribe 机制。仓库源码中的实测数据在一千行 × 十二列的表格上拖拽过程中每次移动约16ms完成基于普通读取。有一个值得警惕的陷阱不要在既会写入选区状态的$effect里读取table.store.get()除非该 effect 确实依赖每个状态切片。一个用于监听列布局的 effect 若读取了全量 store就会在每次选区变化时重跑从而清掉你刚刚做出的选区。正确做法是像上节那样只读取所需的具体table.atoms.slice.get()。另外性能设计还体现在两个层面表格级缓存getCellSelectionBounds是每个单元格读取都会经过的单一缓存索引查找只在失效时执行一次而不是每个单元格各算一次见 cellSelectionFeature.utils.ts。单元格级刻意不做记忆化getIsSelected、getSelectionEdges等原型方法故意不 memoize——注释明确说明为每个单元格分配 memo 闭包与依赖数组的开销远大于对表格级 bounds 缓存做几次整数比较的代价cellSelectionFeature.utils.ts。进阶与合并单元格cell spanning的协作若同时启用cellSpanningFeature选择特性会自动感知合并单元格合并单元格全有或全无地参与选择——每个区间包括 exclude的矩形在代数运算前都会扩张以包住其触碰到的合并区域且展开发生在解析时而非写入时从而保证排序、分页或切换跨行跨列时存储的角点保持稳定见 table_getCellSelectionMergeBounds。同时getSelectionEdges对合并单元格按整条边带探测边界因为单个渲染的边框无法分段。相关逻辑有专门的跨特性测试覆盖cellSelectionSpanAware.test.ts。小结TanStack Svelte Table 的cellSelectionFeature把电子表格式矩形选择的复杂性锚点/焦点角建模、include/exclude 区间代数、显示顺序索引、与排序/固定列/分页的协调收敛在表格核心内部而把交互绑定拖拽、Shift 扩展、Ctrl/Cmd 多范围、UI 渲染选中态、焦点、外轮廓和键盘导航TanStack Hotkeys留在应用层自由定制。只要按本文步骤启用特性、正确选择稳定的 row id、记住拖拽期间onCellSelectionChange会高频触发、并在$effect中只读取需要的 atom你就能构建出既流畅又健壮的单元格选择体验。进一步阅读官方指南docs/framework/svelte/guide/cell-selection.md完整示例源码examples/svelte/cell-selection/src/App.svelte特性注册与默认选项cellSelectionFeature.ts状态解析与单元格 API 实现cellSelectionFeature.utils.ts区间几何运算cellSelectionGeometry.ts核心单元测试cellSelectionFeature.test.ts、cellSelectionRange.test.tsSvelte 示例的端到端测试smoke.spec.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），仅供参考