TanStack Table columnResizingState 接口详解:列宽拖拽的瞬时状态机与实战应用
TanStack Table columnResizingState 接口详解:列宽拖拽的瞬时状态机与实战应用
columnResizingState 是 TanStack Table 表格核心中描述"列宽拖拽过程"的瞬时状态接口,它记录了用户从按下缩放手柄、拖动指针到松开鼠标这一完整交互周期内的全部中间信息。本文以该接口为切入点,逐字段解析其语义,结合 table-core 源码中的特性注册与状态更新逻辑,说明该状态从初始化、写入、消费到重置的完整生命周期,并给出在 React 等适配器中通过 atoms、state 或 onColumnResizingChange 连接 UI 的实战方案,帮助你精确实现列宽拖拽指示器、60fps 渲染等交互能力。
接口定义与属性总览
columnResizingState 在核心包的类型文件中定义,位于 columnResizingFeature.types.ts,完整的接口结构如下:
export interface columnResizingState {
columnSizingStart: Array<[string, number]>
deltaOffset: null | number
deltaPercentage: null | number
isResizingColumn: false | string
startOffset: null | number
startSize: null | number
}
六个属性各司其职,共同刻画一次拖拽的"快照 + 增量"信息。下表是每个字段的语义速览:
| 属性 | 类型 | 含义 |
|---|---|---|
columnSizingStart |
Array<[string, number]> |
拖拽开始时,所有叶子列(leaf column)的列 id 与初始尺寸快照 |
deltaOffset |
number | null |
当前指针位置相对起始位置的像素偏移量(已按方向换算) |
deltaPercentage |
number | null |
当前偏移量相对起始列宽的比例,用于等比缩放计算 |
isResizingColumn |
string | false |
当前正在被拖拽缩放的列 id;无拖拽时为 false |
startOffset |
number | null |
按下手柄时指针的 clientX 起始坐标 |
startSize |
number | null |
拖拽开始时表头(header)的起始像素宽度 |
需要特别强调的是:这是一个"瞬时/临时"(transient)状态,它与保存最终列宽的 ColumnSizingState(即 Record<string, number>,见 columnSizingFeature.types.ts)是两套相互配合的状态。columnResizingState 只存在于拖拽进行中,用于驱动渲染层的"进行中"反馈(如跟随指针的指示条);拖拽结束或每次提交时,计算结果会写入 columnSizing 成为持久化的列宽。
默认值:无拖拽时的初始状态
当表格没有任何拖拽交互时,columnResizingState 处于"空档"状态。该默认值由 getDefaultColumnResizingState() 生成,实现在 columnResizingFeature.utils.ts:
export function getDefaultColumnResizingState(): columnResizingState {
return {
startOffset: null,
startSize: null,
deltaOffset: null,
deltaPercentage: null,
isResizingColumn: false,
columnSizingStart: [],
}
}
可以看到默认状态中所有数值字段均为 null、isResizingColumn 为 false、columnSizingStart 为空数组,语义即"当前没有活动拖拽"。这个默认值同时是两类场景的基准:
- 特性注册时通过
getInitialState为每张表注入初始状态,见 columnResizingFeature.ts; table.resetHeaderSizeInfo(true)会忽略自定义initialState,直接重置回该默认状态。
核心包的单元测试也固化了这一默认值契约(columnResizingFeature.utils.test.ts),当外部状态与默认值不符时会立即在测试中暴露。
六个字段的生命周期与源码语义
要真正理解这六个字段,最好的方式是跟随一次完整拖拽的源码执行路径。缩放交互的核心逻辑全部集中在 header_getResizeHandler 中(columnResizingFeature.utils.ts),一次拖拽会依次填充并清零这些字段。
按下(mousedown/touchstart):写入起始快照
当用户按下缩放手柄时,处理器先做两项检查:
column_getCanResize(column):同时校验列级columnDef.enableResizing与表级enableColumnResizing(两者默认均为true,见 columnResizingFeature.utils.ts);- 触摸事件中若
touches.length > 1(多点触控)则直接忽略。
随后写入起始信息:
const startSize = header_getSize(header) // 记录起始表头宽度 -> startSize
const columnSizingStart: Array<[string, number]> = header
.getLeafHeaders()
.map((leafHeader) => [
leafHeader.column.id,
column_getSize(leafHeader.column), // 每个叶子列的初始尺寸 -> columnSizingStart
])
const clientX = ... // 鼠标或首个触点的 clientX -> startOffset
最终通过 table_setColumnResizing 一次性写入:
table_setColumnResizing(column.table, (old) => ({
...old,
startOffset: clientX,
startSize,
deltaOffset: 0,
deltaPercentage: 0,
columnSizingStart,
isResizingColumn: column.id,
}))
此阶段字段语义:
startOffset:指针按下时的clientX,作为后续计算deltaOffset的零点基准;startSize:被拖拽表头在按下瞬间的像素宽度,用于计算百分比增量;columnSizingStart:记录"所有叶子列"的初始尺寸(而非仅当前列),因为列宽变化可能联动整组叶子列(如分组表头);isResizingColumn:置为当前列的 id,UI 层据此判断"哪一列正在被拖拽";deltaOffset/deltaPercentage:按下瞬间先清零,随后随指针移动更新。
移动(mousemove/touchmove):更新增量字段
拖拽过程中,每次指针移动都会进入 updateOffset('move', clientXPos),计算两个增量字段(columnResizingFeature.utils.ts):
const deltaDirection = table.options.columnResizeDirection === 'rtl' ? -1 : 1
const deltaOffset = (clientXPos - (old.startOffset ?? 0)) * deltaDirection
const startSize = old.startSize ?? 0
const deltaPercentage = Math.max(
startSize > 0 ? deltaOffset / startSize : 0,
-0.999999,
)
字段语义在此阶段体现得最为充分:
deltaOffset:当前指针clientX减去startOffset的差值。默认 LTR 方向下直接取正差;当columnResizeDirection配置为'rtl'时乘以-1反转方向;deltaPercentage:deltaOffset / startSize,即"拖了起始宽度的百分之多少"。Math.max(..., -0.999999)的钳制保证比例不会小于 -1,从而避免列宽被缩成负值或产生NaN——源码中对startSize为 0(零宽列)的情况也做了保护(startSize > 0 ? ... : 0),对应的零宽列回归测试见 columnResizingFeature.utils.test.ts;columnSizingStart与startOffset在移动阶段保持只读,作为计算的参照快照。
值得一提的是,移动事件并非逐帧无条件写入。源码利用 requestAnimationFrame 做了帧合并(coalescing):每帧的第一个移动事件立即应用,帧内后续事件仅记录最新位置并合并到下一帧一次性刷新,避免高刷新率指针设备(可达到显示器刷新率的数倍)造成无意义的重复状态更新;若环境不支持 requestAnimationFrame 则退化为直接更新。相关行为在 columnResizingFeature.utils.ts 中实现,并有专门测试验证"一帧内多次 move 只产生一次更新"(columnResizingFeature.utils.test.ts)。
提交(commit)与松开(mouseup/touchend/touchcancel):计算并清理
deltaPercentage 的实际消费者是"新列宽"的计算。updateOffset 中当 columnResizeMode === 'onChange' 或事件类型为 'end' 时,会基于 columnSizingStart 快照重新计算每个叶子列的新尺寸:
const headerSize = entry[1]
newColumnSizing[entry[0]] =
Math.round(
Math.max(
headerSize > 0
? headerSize + headerSize * deltaPercentage // 有初始宽度:按比例放大/缩小
: deltaOffset / columnSizingStart.length, // 零宽列:均分偏移量
0,
) * 100,
) / 100
这里可以清楚看到 columnSizingStart 的两种用途:对于有初始宽度的列,用 起始宽度 × (1 + deltaPercentage) 等比缩放;对于起始宽度为 0 的列,则把总偏移量均分到每个叶子列上。计算结果随后通过 table_setColumnSizing 写入持久的 columnSizing 状态。
松开指针后,onEnd 处理器做两件事(columnResizingFeature.utils.ts):
- 提交最终的
end位置(touchend事件不携带触点坐标,会回退到最近一次移动记录的位置); - 将
columnResizing状态重置回"空档":
table_setColumnResizing(column.table, (old) => ({
...old,
isResizingColumn: false,
startOffset: null,
startSize: null,
deltaOffset: null,
deltaPercentage: null,
columnSizingStart: [],
}))
即一次拖拽结束后,六个字段全部回到默认值,等待下一次交互。此外,touchcancel(浏览器接管手势、标签页切换等场景)也会触发同样的清理与提交逻辑,避免非 passive 的 touchmove 监听器长期残留于 document 上。整个提交过程被 table._reactivity.batch() 包裹,保证"列宽写入 + 状态重置"只触发一次通知刷新(对应测试见 columnResizingFeature.utils.test.ts)。
相关配置选项
columnResizingState 的行为由三类表选项调控(定义见 columnResizingFeature.types.ts):
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
columnResizeMode |
'onChange' | 'onEnd' |
'onEnd' |
onChange 在拖拽过程中逐帧提交新列宽;onEnd 仅在拖拽结束时提交。默认值来自 columnResizingFeature.ts |
columnResizeDirection |
'ltr' | 'rtl' |
'ltr' |
决定 deltaOffset 的方向系数,RTL 布局下取反 |
onColumnResizingChange |
OnChangeFn<columnResizingState> |
内部状态更新器 | 瞬时状态每次变化时回调;配合 state.columnResizing 做外部受控 |
默认选项通过 getDefaultTableOptions 注入(columnResizingFeature.ts),其中 onColumnResizingChange 默认指向 makeStateUpdater('columnResizing', table),即写入表格内部状态;只有当你显式传入 state.columnResizing 时,才需要自行提供回调。
如何消费该状态:连接 UI 的三种方式
1. 读取 isResizingColumn 与 deltaOffset 渲染拖拽指示器
最常见的消费场景是渲染跟随指针的"列宽指示条"。官方指南给出的经典写法是(详见 React 列宽缩放指南):
<ColumnResizeIndicator
style={{
transform: header.column.getIsResizing()
? `translateX(${table.state.columnResizing.deltaOffset ?? 0}px)`
: '',
}}
/>
其中 column.getIsResizing() 正是对 state.columnResizing.isResizingColumn === column.id 的封装(columnResizingFeature.utils.ts)。指示条的横向位移直接取自 deltaOffset,这就是该字段存在的意义:让 UI 在列宽正式提交前,就能以 1:1 的像素精度跟随指针。
2. 通过 header.getResizeHandler() 触发状态写入
你不需要手动构造 columnResizingState——预置的缩放处理器 header.getResizeHandler() 会接管完整的状态机(鼠标与触摸均支持):
<ColumnResizeHandle
onMouseDown={header.getResizeHandler()} // 桌面端
onTouchStart={header.getResizeHandler()} // 移动端
/>
该处理器由 columnResizingFeature 挂载到 Header 原型上(columnResizingFeature.ts),内部实现即上文追踪的完整生命周期,并自动完成事件监听器的安装与清理。
3. 外部状态管理:atoms 与受控回调
columnResizingState 是瞬态高频更新的状态,官方推荐在 v9 中使用外部原子(atom)接管,以获得细粒度订阅、避免不必要地重渲染整个表格组件:
import { useCreateAtom, useSelector } from '@tanstack/react-store'
import type { columnResizingState } from '@tanstack/react-table'
const columnResizingAtom = useCreateAtom<columnResizingState>({
columnSizingStart: [],
deltaOffset: null,
deltaPercentage: null,
isResizingColumn: false,
startOffset: null,
startSize: null,
})
const columnResizing = useSelector(columnResizingAtom)
const table = useTable({
features,
columns,
data,
atoms: {
columnResizing: columnResizingAtom,
},
})
若沿用 v8 风格的受控模式,state.columnResizing + onColumnResizingChange 依旧可用,但粒度较粗:
const [columnResizing, setColumnResizing] = useState<columnResizingState>({
columnSizingStart: [],
deltaOffset: null,
deltaPercentage: null,
isResizingColumn: false,
startOffset: null,
startSize: null,
})
const table = useTable({
features,
columns,
data,
state: { columnResizing },
onColumnResizingChange: setColumnResizing,
})
两种方式传入的初始值都应以上述六字段完整形态给出(等价于 getDefaultColumnResizingState()),否则运行时可能因缺字段产生意外行为。
进阶:利用瞬时状态实现高性能拖拽
columnResizingState 是高频瞬态状态,其更新频率直接关系到渲染性能。将"瞬态拖拽信息"与"持久列宽"分离,正是 TanStack Table 支持 60fps 缩放的关键设计。社区实践(见 performant column resizing 示例 与 React 指南的高级性能章节)通常采用以下组合拳:
- 让表格主体组件不订阅任何缩放相关状态,避免每帧重渲染整个表格;
- 在
useLayoutEffect中订阅table.atoms.columnSizing,把列宽直接写成--col-<id>-size形式的 CSS 变量,由浏览器负责布局,React 零参与; - 只有"激活指示器"这类必须响应的小组件才通过
table.Subscribe订阅isResizingColumn/deltaOffset对应切片。
由于核心的缩放处理器已把指针事件合并到每动画帧一次,再配合"仅订阅所需切片"的外层策略,即使表格单元格渲染成本很高,拖拽过程也能保持流畅。
补充:相关状态与 API 一览
- 持久列宽状态
ColumnSizingState(Record<string, number>)及table.setColumnSizing、table.resetColumnSizing、column.getSize()等 API 见 columnSizingFeature.types.ts; - 瞬时状态的操作入口:
table.setColumnResizing(updater)与table.resetHeaderSizeInfo(defaultState?),定义于 columnResizingFeature.types.ts,前者路由更新器到onColumnResizingChange,后者重置到initialState.columnResizing或默认空档状态(columnResizingFeature.utils.ts); - 功能启用开关:表级
enableColumnResizing(默认true)与列级enableResizing(默认true),二者同时为真时column.getCanResize()才返回true; - 框架接入示例:功能需按
columnSizingFeature在前、columnResizingFeature在后的顺序注册,完整配置示例见 React 列宽缩放指南,其余适配器(Vue、Solid、Svelte、Angular 等)的指南位于 docs/framework 对应目录。
小结
columnResizingState 虽小,却是 TanStack Table 列宽缩放交互的"心脏":startOffset 与 startSize 定义拖拽基准,deltaOffset 与 deltaPercentage 表达指针增量,columnSizingStart 保留全体叶子列的起始快照用于等比计算,isResizingColumn 标记当前活动列。理解这六个字段的写入时机与消费方式,你就能精确控制拖拽指示器、提交时机(onChange/onEnd)乃至 60fps 渲染策略,在任意适配器中构建出专业、顺滑的列宽缩放体验。