用途:为 TanStack Table 主体单元格提供无状态的合并(跨行、跨列)能力。合并完全派生自实际渲染的行,表级合并索引经 memo 化重建,单元格读取为 O(1)。排序、过滤、分页、行固定只改变相邻关系,合并随之自动变化且不持久化。
主要能力:用 spanRows 让列按值做纵向合并,true 表示相邻渲染行在 Object.is 下相等即合并,默认比较下 nullish 值不合并,可用谓词自定义;谓词以 run 的首行(anchorRow/anchorValue)为锚,保证传递性。用 spanColumns 按行声明横向合并,按渲染顺序计入可见列并夹到所在固定区域末尾,Infinity 表示“本区域剩余列”,不跨越 start/center/end 固定边界。纵向 run 仅在列跨度一致时加入,整行摘要不会并入上方数据 run。
使用方式:在 tableFeatures 注册 cellSpanningFeature;列定义加 spanRows(布尔或 ({anchorValue,value}) => boolean)与 spanColumns(({row}) => number);渲染可见单元格时读取 cell.getRowSpan() 与 cell.getColSpan(),当 rowSpan===0 或 colSpan===0 时跳过该单元格(cell.getIsCovered() 等价),否则输出 td 的 rowSpan/colSpan。关闭方式:表选项 enableCellSpanning: false 关闭全部,列定义上的同名标志只关该列且优先于表选项。
适用场景:需要在已排序/已过滤/分页结果中按相邻相等值合并单元格,或按行做整行摘要式横向合并。合并感知的单元格选择在同时注册 cellSelectionFeature 时自动生效。
限制:值合并只合并相邻相等值,不排序、不分组,需先排序或让数据相邻;不要用源数据预计算 span,否则排序过滤分页后会错行;run 会被分页模型截断,不跨页延续;分组列上 spanRows 被忽略;不要把被覆盖单元格渲染成 rowSpan={0}(HTML 中 rowspan="0" 表示延伸到行组末尾,会错位),正确做法是跳过不渲染。完整 API 可在 node_modules/@tanstack/table-core/dist/features/cell-spanning/ 查看,包括 cell.getRowSpan()、cell.getColSpan()、cell.getIsCovered()、table.getCellSpanIndex() 及 spanRows/spanColumns/enableCellSpanning 选项。