用途:在 TanStack Table 中把具有稳定 ID 的行固定到顶部、中部、底部三个区域,用于表格布局与可见性控制。基于 table-core 的 core 与 table-features 构建。
主要能力:通过 rowPinningFeature 注册功能,使用 table.getTopRows()、getCenterRows()、getBottomRows() 获取各区域行;行固定状态本身不负责 DOM 样式与位置,需要渲染器自行控制顺序与 sticky 布局。keepPinnedRows 默认 true,固定行在过滤或分页移出中部行模型时仍保留在固定区域;设为 false 时,固定行仅限当前过滤和分页结果中的行,需按产品行为明确选择。
使用方式:以 tableFeatures({ rowPinningFeature }) 组合功能,传 getRowId 返回稳定行 ID,并按需设置 keepPinnedRows。渲染时显式遍历各区域:table.getTopRows()、table.getCenterRows()、table.getBottomRows(),若视觉顺序重要需逐区域渲染。固定行的 sticky 定位需自行设置,如 topRowElement.style.position = 'sticky'。
限制与注意:不要用索引作为行 ID,排序、过滤、分页和插入都会改变索引,应使用实体自身 ID。不要期望调用 row.pin('top') 自动出现粘性行,固定状态不写样式也不放置 DOM。keepPinnedRows 两种取值都无绝对对错,取决于产品需求。
API 发现:可查看 node_modules/@tanstack/table-core/dist/features/row-pinning/ 了解区域 getter、行 API 与 keepPinnedRows 语义。