08-table 深导览

范围：本导览只做 03-components/08-table 这 7 篇之间的跨篇路由——你手上这条「表格类症状」该翻组件侧哪一篇，还是该直接跳到基座侧。渲染内核（测量行、固定列 offset、克隆表头、单元格拆分、滚动同步）、table-core 的派生顺序与状态袋形态、虚拟化两套引擎的窗口数学，分别在 I05、I06、I08 已经论证完，本篇一律不复述；主题 Token 与样式表身份归 A03、A04，props 默认值与注入链归 A05、A06，受控合并语义归 I13，语言包供给侧归 I11。

一、这一层在解决什么

这一族 7 篇里只有 4 个「把一份数组渲染成结构化条目」的实现，另外 2 篇是虚拟化容器、1 篇是类横写。它们的差别不在功能多少，而在三个真源各自握在哪一层：列定义的真源、状态袋的真源、可见窗口的真源。table 把列编译成数组后交给内核，本体一行 DOM 都不产出（C08-01 论点 1）；data-table 把列的本体做成 VNode，columns prop 被降级成「造 VNode 的原料」（C08-02 论点 3）；tree-table 的列只能由默认插槽的子节点产出（C08-00 论点 2）；list 干脆不认识「行、列、单元格」这三个概念（C08-05 §一）。先定住这三个真源，后面所有「传了不生效」的症状都能一眼归层。

状态流向在本族是三条互不兼容的路线，不是一条路线的三种粗细。table 是单向闭环：props 进、五段编译链在内核渲染期回调、一次 onChange 出，而载荷里的数据是重跑管道算出来的、不是复用渲染用的那份（C08-01 论点 3）。data-table 是反向的：12 个独立 ref 组成状态袋、39 个具名事件各自写回，翻页一次对外发四个信号（C08-00 §三、I06 论点 5、C08-00 §五）。tree-table 最特殊：勾选的真源在调用方，展开才是半受控，于是同一张表里出现两种心智模型（C08-03 论点 2、I06 论点 6）。三者的事件命名风格也不统一，只能当成三套契约对待，这一点是迁移成本而不是 bug（C08-00 §三）。

分层上有三处断裂，读者必须记住它们决定了「改动的爆炸半径」：渲染内核只有一条入边（来自 table），table-core 有两条入边但深度完全不同，data-table/composables/ 是一个只被自己测试引用的悬空框（C08-00 §三）。直接含义有两条：任何「修表格渲染 bug」的默认落点只在 table/，另外两张表是自己手写 DOM 的（C08-00 论点 1）；而任何「修 table-core 排序」的落点大概率在没人调用的那一份上（I06 论点 3、I06 坑 1）。

因此本篇最重要的用法是同一症状的两层归位。最典型的是「列没写 key」：在组件侧它表现为排序与筛选状态在增删列后串到别的列（C08-01 坑 1），在内核侧它表现为测量宽度串到另一列（I05 坑 3）——同一个键，两个后果，两条修复路线，谁都不覆盖谁。第二个例子是 lazy：data-table 的 lazy 是关掉本地管道的合取守卫（C08-00 坑 3），tree-table 的 lazy 是管道顶端一次 return（C08-00 §三）；「服务端分页不生效」这句话在两张表里是两件事。

虚拟化在本族只有一条真实通路，它同时改写了数据管道与 DOM 选择器（C08-00 论点 4）。两份虚拟化拷贝里，库内实引擎是被 data-table 直接导入的那一份，另一份是库内零消费者的公开件（C08-07 论点 3、C08-06 §一）；它们的窗口数学、高度策略与 overscan 归 I08，本篇不重列。选型判据只有一条：行高能不能保证恒等——能，用声明式引擎；不能，换带测量回路的那一份（I08 论点 3）。

派工提示里的「ProTable / 可编辑表格」这一层在本族没有对应篇目，7 篇里没有任何一篇出现这个组件，本篇不虚构它。真实存在的「可编辑」通道只有 data-table 的列级编辑插槽（children.editor，编辑态与非编辑态在同一个渲染函数里分流，C08-00 论点 3），而另一个常被拿来对照的行内编辑组件属于 06 类、并且不被本仓任何组件依赖（C06-05 §一）。想给表格配一套「声明式可编辑表格」的人，正确的读序是 C08-02、C08-00 论点 3、C06-05 §一，不是去找一个不存在的上层组件。

二、选型表（近义组件怎么选）

三、坑索引（症状 → 哪一篇的坑 N）

族谱一：传了不生效、写了不上身（契约面）

• 根节点上找不到用户写的 class、style、id，原生事件也不触发 → C08-02 坑 1；同款两处还有 C08-06 坑 2、C08-07 坑 1 与 坑 2，机制侧口径归 A06 坑 2。
• 给 data-table 传 tableProps 反而把内部基座类名拆掉 → C08-02 坑 2；同族的「展开顺序」判读要注意 on 事件键不进覆盖语义，见 A06。
• 排序相关的两个「不生效」长得一样：档位点了回不去是 undefined 乘负一塌成 NaN 并一路传进比较器（I06 坑 2）；给列传 sortOrder: undefined 把列永久钉成受控则是另一条判据（C08-01 坑 2）。
• show-gridlines、striped-rows、row-hover 三个开关永远无效 → C08-02 坑 4，且它前面还压着一层「样式表整条错位、改了也看不见」（C08-02 坑 3）。
• List 传 extra 什么都不出现、loading 传对象不带 spinning 就没遮罩 → C08-05 坑 1、C08-05 坑 3；水平布局下条目 extra 只留第一个节点是第三条（C08-05 坑 4）。
• 改 prefixCls 只改到根节点，条目类名留在旧前缀 → C08-05 坑 2；同类「喂给样式钩子的前缀不是本组件的、于是同一份样式注册成两张表」的判形见 A04 论点 1。
• 「改了样式没反应」有两种相反的成因 → C08-02 坑 3 与 C08-05 坑 8 是同族的两面：前者是规则与类名互不相认，后者当时是四条选择器（.xy-list-spin、.xy-list-loading .xy-list-spin-nested-loading、窄屏 .xy-list-action、等不到根类名的 .xy-list-empty footer 边框）全部挂在代码从不生成的类名上。C08-05 那四条已在 2026-09-29 接回真实类名，判别方法只有一个：把「组件生成的类名集合」与「样式表引用的类名集合」相减，两个方向都要看。修完的代价是加载态高度与窄屏边距从此真的生效，所以这类改动不再属于「删了也不会变」的安全操作，C08-02 坑 3 已在 2026-09-30 修完：155 处 &__ 与 40 处根级 &-- 一次对齐到 DOM 的单横线命名（公开类名不变），验收读的是注入到 document 的真实 CSS，三条判据在基线全红；同篇 坑 4 同日一并修掉：gridlines/striped/hoverable 缺的是类名生产者（根类名唯一来源 DataTable.tsx:2299 的 dataP 里没这三个键），补上之后 12+3+2 条规则才有宿主。这条与坑 3 是两个独立断点——样式表对齐了类名不等于开关生效，两端要分别相减。
• ConfigProvider 的 direction 与全局文案对某张表零效果 → C08-00 坑 7，供给侧整体缺失面在 I11。
• 受控 selectedRowKeys 只给值不给回写，勾选点了没反应 → C08-01 坑 4；tree-table 侧对应的是「本地态吞掉受控语义」（C08-03 坑 6）；合并语义的机制归 I13。
• 服务端分页忘传 total 时翻页像失效 → C08-05 坑 5（total 缺省被 dataSource.length 顶替，越界页码被夹回）。

族谱二：数据和状态不对（管道面）

• 开了虚拟滚动后点表头不排序、筛选也失效 → C08-00 坑 3；新增派生阶段忘复制那条门控是它的镜像症状（I06 坑 8）。
• lazy 模式下「服务端分页不生效」长得各不相同 → data-table 的 lazy 是关掉本地管道的合取守卫（C08-00 坑 3），tree-table 的 lazy 是管道顶端一次 return（C08-00 §三）；两条判据不能互相套用。
• 翻页后展开全收起、勾选却还在 → C08-03 坑 2，同一条也在 I06 坑 5 登记；两处结论一致，行号定位以 C08-03 坑 2 为准。
• 「全选」其实选的是全量而不是本页 → I06 坑 6；tree-table 没有表头全选框，勾选只能逐行发起（C08-03 §一）。
• 取消勾选后选中集合里留下全 false 的空壳条目、批量勾选只发一次事件 → C08-03 坑 3、C08-03 坑 4。
• preserveSelectedRowKeys 打开后行数组里混进 undefined → C08-01 坑 5；跨页能解析到记录的前提见 C08-01 坑 9。
• @change 在大表上把管道跑两遍、排序响应翻倍 → C08-00 坑 6（triggerOnChange 为组装 currentDataSource 重跑排序与过滤）。
• data-table 的非受控过滤不成立、双向绑定的多列排序元数据静默失同步 → I06 坑 7、I06 坑 3。

族谱三：DOM、类名与结构（渲染面）

• 切换列、拖出新列后表头整块空白一帧 → I05 坑 1；表格在隐藏容器里首次挂载，固定列叠在一起 → I05 坑 2。
• 改动表格外层 DOM 让列宽调整与滚动定位静默失效 → C08-00 坑 4；根因是同一选择器被硬编码两遍、没有共同常量可单点改（C08-00 坑 4 定位段）。
• data-xy-scrollable 永远渲染不出来 → I06 坑 4；-fix-sticky 与 -cell-fix-left-all 是双向都断的类名契约（I05 坑 5）。
• 鼠标停留时行 hover 色自己消失、收起的展开行仍占 DOM → I05 坑 7、I05 坑 8。
• 同页两张 tree-table 的冻结列偏移互相污染 → C08-03 坑 5，因为它读的是全局 document 而不是本表根节点。
• 树表格数据少写一层 data，一点展开就全开 → C08-03 坑 1；这是「节点三段式」约定被违反的直接后果（C08-03 论点 3）。

族谱四：虚拟化（窗口面）

• 越滚越偏、滚到底留白或提前见底 → I08 坑 3；virtual-scroller 那一份还额外缺一个数值兜底（C08-07 坑 3），itemSize 缺省为 0 时窗口数学直接塌缩（C08-06 坑 3）。
• 程序化滚动一次之后，缓冲带被永久旁路、每帧重排 → C08-06 坑 1，该篇已核实同款存在于另一份拷贝；scrollToIndex 越界与未挂载全静默 → I08 坑 4、C08-07 坑 4。
• 快速滚动后条目里的输入框状态串到别的行 → I08 坑 5；内部基座那一份的两个对应症状是键不唯一与条目必须单根（I08 坑 1、I08 坑 2）。
• SSR 首屏虚拟化容器是空的 → C08-06 坑 4。
• 把 numToleratedItems 当固定 prop 传却半失效 → C08-06 坑 5。
• 修了一个虚拟化的 bug，另一个用户还在犯 → I08 坑 6、C08-07 坑 5，改前先对两份文件跑差异。

族谱五：标签、导出与「改了个寂寞」（交付面）

• <xy-row> 在运行时到底是哪个组件 → C08-00 坑 5；登记粒度不等（运行时六个标签、类型面只有一条）见 C08-00 论点 5。
• 给 tree-table 用库里现成的列组件，表头空白且无报错 → C08-00 坑 1；本篇第五节有一条现 grep 的仲裁。
• 在 data-table/composables/ 里改 bug，测试全绿、行为不变 → C08-02 坑 5、I06 坑 1；为什么它比线上版本更正确却没接线，见 I06 §六。
• 改 table-core 的 flat 分支去修 data-table → I06 坑 1；只有 tree 侧那一份会传导到组件。
• 从包根 import type 拿到的列类型永远是 table 的那一份 → C08-00 论点 5；这条归属是怎么被钉住的，机制在 A02 论点 6，想顺手加一条锁会被 A02 坑 7 反噬。
• 改组件 name 或目录名后包根导出面漂移 → C08-00 坑 1 末段，交付链的通用条目见 A02 坑 3、A02 坑 6。
• loader 返回形状改了没有类型闸门 → C08-07 坑 6（悬空类型让 data-table 的列类型声明失去约束）。

四、改动路线（想动 X 之前先读哪几篇）

• 要给表格新增一类交互（半选、分组、列固定新语义）：先读 I06 论点 9（要动的「7 + 2」处清单，其中两处是生成物与快照），再读 C08-00 论点 1（三张表零共享，新增能力要落几个目录）与 C08-02 论点 1（同一逻辑的第二份拷贝已经存在过一次）。
• 要修 data-table 的排序、过滤或分页行为：落点是 DataTable.tsx 的内联函数，不是 table-core 的 flat 分支也不是 composables/，顺序读 I06 坑 1、I06 坑 2、C08-02 坑 5、C08-02 论点 4。
• 要动列定义形态（数组 prop 与子组件 DSL 之间切换）：读 C08-00 论点 2、C08-02 论点 3、I06 论点 1；内核侧只需 columns: any[] 与列属性访问器这一条判据在 I06 §六。
• 要在表格里上虚拟滚动或换引擎：读 C08-00 论点 4（这条通路同时改写了数据管道与 DOM 选择器）、I08 论点 3 与 I08 论点 6、C08-07 §六（换引擎的真实成本在插槽契约形状，不在窗口数学）。
• 要改表格外层 DOM 或类名：读 C08-00 坑 4（两处硬编码选择器）、C08-02 论点 2（样式表与 DOM 两套命名从不错位）、I05 §六（类名是跨层契约且没有编译期保护，断链实例是 I05 坑 5）。
• 要动 tree-table 的勾选、展开或键盘导航：读 C08-03 论点 1（可见行由渲染递归产生，没有可见行数组）、C08-03 论点 2、C08-03 论点 5、I06 论点 6；接虚拟滚动会首先推翻「折叠子树不存在」这个前提（C08-03 §六）。
• 要统一三张表的事件契约或做迁移：读 C08-00 §三（一次 change 对三十九个事件，命名风格三份）、C08-01 §六（源码里作者自陈的受控寄生与计划）、I06 §六（事件名 value-change 与 change 的漂移就是上一次没接线的直接负债）。
• 要修「全局配置对某张表不生效」：读 C08-00 坑 7，再回 A05（注入链与兜底写法）与 A06 坑 5（给需要「未传判定」的键写默认值，同时打断受控判定与注入）；data-table 只接 prefixCls 这一事实本身在 C08-00 §五。
• 要动 table 的列编译链或它与内核的握手：读 C08-01 论点 1、C08-01 坑 6（顺序的隐式前置条件）、I05 论点 6、I05 论点 10；「门禁字符串必须两边一致、编译发生在内核渲染期」这笔代价记在 C08-01 §六，反向依赖那条边在 I05 §一 被明确标成不应存在。

五、两处口径冲突的仲裁（已现 grep）

冲突 1：tree-table 的列到底能不能从 columns prop 进。 C08-00 §二 写的是「它的列定义只能从 columns prop 进（treeTableTypes.ts:162）」，而同篇 论点 2 写的是「treeTableProps() 里根本没有 columns 这个 prop，列只能由插槽子节点提供」。两处口径互斥，现查后以 C08-00 论点 2 为准：

grep -n -e "^export const treeTableProps" -e "^export const treeTableRowProps" -e "columns:" \
  packages/xiaoye-ui/src/tree-table/treeTableTypes.ts
# 95: treeTableProps；154: treeTableRowProps；162 的 columns 落在后者体内
grep -n "props.columns" packages/xiaoye-ui/src/tree-table/TreeTable.tsx   # 0 命中

packages/xiaoye-ui/src/tree-table/treeTableTypes.ts:162 那个 columns 属于行级 props 工厂（同文件 :154），主组件工厂 :95 里没有它，主实现也不读 props.columns。C08-03 §二 从收集端印证同一结论（TreeTable.tsx:68 的收集器加 :98 到 :101 的兜底），因此按 C08-00 §二 那句话去改代码会直接改错方向。

冲突 2：column、columngroup、row 是不是 DataTable 与 TreeTable 的共用层。 实测它们只存在于 data-table/ 目录内、其中只有 column 被生产代码引用，结论以 C08-02 §一 为准——不是共用层：

grep -rn -e data-table -e column/ -e columngroup -e row/Row \
  packages/xiaoye-ui/src/tree-table --include='*.ts' --include='*.tsx' | grep -v __tests__   # 0 命中

tree-table 的非测试源码对这三件零引用，它们不是共用层；tree-table 之所以看起来「也用列组件」，是因为它的收集器按字符串 'Column' 匹配，而库里没有任何组件的 name 是它（C08-00 论点 2）。这条差别有实用后果：给 data-table 补列组件相关改动不会传导到 tree-table，反之也一样，别按「共用层」的心智去评估回归面。

登记漂移已清（2026-10-02）：本类各篇「读者坐标」的分母已按目录内实际篇数（7）重排，data-view 移除后的空号保留不补位。