Table

何时用

展示结构化二维数据（用户列表、明细表等）且需要排序/行选择/树形/虚拟滚动等表格能力时用。列定义直接复用 TanStack 的 ColumnDef，不发明平行 API。它是底层表格皮肤——需要查询区 + 工具栏 + 集成分页的完整列表页用 ProTable（它内部就包了 Table）；单元格可编辑用 EditableTable；纯垂直列表用 List。

导入

Props

Events

Slots

列 meta 增量（写在 ColumnDef.meta）：

列宽走 TanStack 原生的 ColumnDef.size / minSize / maxSize（不另发明 width / min-width）：
size → width、minSize → min-width、maxSize → max-width，th 与 td 用同一口径的内联 style（不使用 <colgroup>）。

组合原语

TableRoot / TableHeader / TableBody / TableFooter / TableRow / TableHead / TableCell 七件薄包，
给「结构由业务自己写、只想要库的表格皮肤」的表。判据不是「Table 不够用」，而是配置表达不了结构：
一行里嵌两层、整行是一个编辑器、按数据把一条拆成三行 —— 写成 ColumnDef[] 就是把可读的表格结构
翻译进 cell 回调，代码只会更难读。所以两条路并存：数据驱动 + 要排序/分页/冻结列走高层 Table，
其余走原语。皮肤（密度档位、分隔线、悬停、选中底色）与高层 Table 同源，不是「长得差不多的另一套」。

TableRoot

TableHeader / TableBody / TableFooter 只接原生 <thead> / <tbody> / <tfoot> 属性，外加一个 ref。

七件原语都收 `ref`，落在各自的那个 DOM 节点上（TableRoot → 滚动容器 div，其余 → thead / tbody / tfoot / tr / th / td）。TableRoot 这一个尤其要紧：横向滚动状态只存在于那层 overflow-x-auto 的 div 上，自绘底部悬浮横滚条、ResizeObserver 观察容器宽、「滚到第 N 列」、两张表联动横滚都得从它拿。

TableRow / TableHead / TableCell

TableRow 的分隔线 / 悬停 / 斑马纹按所在段自动区分（表头行不 hover、不斑马纹，也不吃 last:border-0
—— 单行表头就是最后一行，那条规则会把表头底边线抹掉），消费方不用自己记这个差别。

禁忌 / 坑

• 列宽只认显式写在 ColumnDef 上的 size/minSize/maxSize。没写 size 的列不会落宽度样式（保持内容自适应）——这是刻意的：TanStack 会把 defaultColumn（size 150）合并进每个 columnDef，照着 getSize() 无脑出宽度会把整张表钉成等宽。
• `columns` 必须 memo。 cell 函数经 TanStack 的 flexRender 被当作组件类型渲染，identity 一变整格卸载重挂（不是重渲染）。展示表只是白烧性能；格子里有输入框时直接坏功能：受控输入框每敲一个字失焦 + 光标跳到末尾，挂了 onBlur 提交的还会被重挂时的 blur 触发误提交（半截值直接进库），非受控的则被 defaultValue 复位丢字。三个症状都不长得像「columns 没 memo」，排查会先怀疑输入框本身。同理 useMemo 的依赖里不要放逐键变化的输入值 —— 那等于没 memo；行内编辑优先让输入框非受控（defaultValue + 提交时读 DOM）。
• 写薄包装转发原语 props 时，TableHeadProps / TableCellProps 的 align 得跟着 Omit 一次：那两个接口把原生的 align（更宽的联合，含 justify / char）换成了 "left" | "center" | "right"，直接 extends ThHTMLAttributes<…> 转发会类型不兼容。
• 表头吸顶要 stickyHeader 加 maxHeight：sticky 需要一个真的会纵向滚动的祖先，而外壳默认只有 overflow-x-auto、没有高度约束。业务侧套 [&_thead]:sticky 也够不到（中间隔着这层 overflow 容器）。
• 「表内横滚 + 表头吸页面」是拿不到的组合，这是 CSS 的硬约束不是实现取舍：overflow-x: auto 会让另一轴的 visible 一并计算成 auto，于是那层外壳自己成了 scrollport，把表头锚死在它身上（实测 Chromium：页面下滚时表头直接划走，同一张表换成 overflow: visible 的外壳才稳稳停在 top: 0）。所以 stickyHeader="scrollParent" 下组件主动去掉外壳的 overflow-x-auto，横向溢出交给外部滚动容器；stickyScrollbar 在这一档下没有可镜像的容器，会被忽略并告警。要保住表内横滚就只能用 "self" + maxHeight。
• renderRowExtra 与 renderExpandedRow 是两件事，别拿后者顶前者：明细面板每行只能一条、必须展开态、且强制前插一列展开器。「这条工作经历下面常驻挂 N 张证书」属于行的一部分，不是折叠明细。
• renderRowExtra / footer 返回的是裸 `<tr>`，组件不替你包 <tr><td>：包了就再也表达不了「一条附属行拆成三格」。整宽行的 colSpan 一定要用回调给的 ctx.colSpan —— 它含自动前插的选择 / 展开器 / 拖拽手柄列，columns.length 算出来的数会短一到三列，表现是最右边空出一块。
• renderRowExtra 与 cellSpan 不能同开（同 renderExpandedRow）：附属行插在数据行之间，纵向合并会跨过它们。同开时静默不合并 + dev 告警。
• renderRowExtra 与 virtual 同开会让虚拟化的行高估算失准（它按「一条数据 = 一行 rowHeight」撑占位行），表现是滚动漂移 / 底部留白。组件只告警不关闭（关了附属行就没了，比错位更难查）；附属行条数固定时把 virtual.rowHeight 调成「数据行 + 附属行」的总高即可。
• 宽表的宽度下限用 minWidth，不要写进 `className`：className 落在滚动外壳上，min-w-* 会让容器再也收不窄 → scrollWidth === clientWidth → 横滚条永不出现，超出视口的列被祖先裁掉且滚不出来。宽窗口下自查不到，只有收窄到阈值以下才暴露。
• meta.whitespace 与 meta.ellipsis 是互斥的两条路：截断本身要求单行。要「不截断、只换行」的核对型表格，用 whitespace: "normal" + maxSize 限宽 + verticalAlign: "top"（换行列不配顶对齐，同一行的短单元格会浮在中线上、与长单元格首行对不齐）。
• meta.ellipsis 要生效必须该列有确定宽度：给显式 size（会自动兜成 max-width）或 maxSize，或整表 layout="fixed"；否则 auto 布局下列被内容撑开，省略号永远不出现。Tooltip 全文取该列的原始值（string/number），自定义 cell 渲染成非文本（图片/按钮）时只截断不挂浮层。
• 固定列（meta.sticky）的 offset 由 getStart/getAfter 按 getSize() 累加得出，所以固定列的渲染宽会被强制钉成 `getSize()`（没写 size 就是默认 150）——想要多宽就显式写 size。同时内容要够宽触发横滚才看得到效果。
• resizable 会强制 layout="fixed"（拖拽必须有确定列宽）。fixed 下表宽 = 各列 getSize() 之和，窄于容器时靠 min-w-full 撑满、列宽被浏览器按比例放大——那种情况下没有横滚，固定列 offset 也就无从体现。
• cellSpan 的回调只在没被合掉的格子上跑，所以「与上一行同门店就合并」的写法是：在段首返回整段长度（while (rows[i + n]?.store === rows[i].store) n++），后面几行根本不会被问到。从 el-table 直译过来的 [0, 0] 写法也认（返回 rowSpan: 0 即该格不渲染）。
• cellSpan 拿到的 rowIndex 是渲染顺序的下标（排序/筛选之后），rows 也是同序的 —— 这正是 el-table 里「开了列排序合并就整片错位」那个坑的解法：判断只比数据，不依赖原始下标。
• cellSpan 与 virtual、renderExpandedRow 不能同开：前者只渲染可见窗口、跨窗口的纵向合并没有落点，后者会把明细 <tr> 插在数据行之间、被纵向合并跨过。同开时组件静默不合并并在 dev 下告警（而不是画出一张错位的表）。
• cellClassName 落在 <td> 本体上、排在类名串最后，所以同名工具类（背景、文字色）会盖过斑马纹 / 固定列底色 —— 这正是「整格着色」要的效果；不想盖住固定列底色就别在固定列上返回 bg-*。回调对内建前插列（__select__ / __expander__ / __drag__）同样会跑，按 ctx.columnId 自行排除。
• meta.filterRender 是回调不是组件（同 ColumnDef.cell）：不要在回调体内直接调 hooks，状态放进你自己的控件组件里。清除某列筛选是 setValue(undefined)，不是写空串（空串是一个「按空串筛」的有效值）。
• filterPlacement="row" 那一行渲染成 <thead> 里的 <td> 而不是 <th>：装的是控件不是列名，落成表头单元格会被读屏当成第二层列名念。一列都不可筛选时整行不渲染。
• cellSpan 与冻结列（meta.sticky）同开时，横向合并不要跨过冻结边界：冻结列的 offset 按未合并的原始列宽累加，跨边界的 colSpan 会让贴边那格错位。
• 多级表头下，冻结（`meta.sticky`）只作用到叶子列：冻结是按叶子列的累计宽度算 offset 的，横跨若干列的组名格没有自己的 offset，横滚时它会跟着内容走、只有下面那行的列头贴住边缘。分组表 + 冻结列的组合请把要冻结的列放在组外（独立列纵向跨满，观感与冻结一致）。
• 多级表头的排序 / 筛选挂在叶子列上，组名那格不出排序按钮：组列本身没有取值器，排的是哪一列没有定义。要按组内某列排就在那个叶子列上开 enableSorting。
• 分组时列宽写在叶子列上（size / minSize / maxSize）。写在组上不会分配给下面的列——组的宽度是各叶子列之和。
• 行选择框挂在每一行上，被纵向合并的行仍然是独立的一行（选择/拖拽都按行算），合并只是视觉上的并格。
• virtual 是可选依赖（@tanstack/react-virtual），需手动安装；仅推荐大数据平铺表，不建议与树形/明细面板同开。
• bordered 默认 true 自带外框——嵌进 ProTable 或其他卡片容器时置 false，否则双层描边。
• 排序/选择/展开/筛选均「不传受控 prop 即内部非受控」；要受控就成对接上 xxx + onXxxChange。
• rowHref 走 window.location.assign 整页跳转——Next.js/SPA 里会丢客户端路由状态，客户端跳转请用 onRowClick + router.push。onRowClick 与 rowHref 同传时 onRowClick 优先，导航不执行。
• onRowClick 与 onRowDoubleClick 同传时，浏览器双击必然先派两次 click，所以 onRowClick 会先跑两次。请保证它的动作可重入、且不与双击语义冲突（典型安排：单击选中、双击进编辑）。
• 行点击的冒泡隔离按选择器识别行内交互元素（a/button/input/select/textarea/label + role=button/checkbox/switch/menuitem）；自定义 cell 里的可点元素若不属于这些（如裸 div 加 onClick），点击会同时触发行级动作——给它补上语义 role 即可隔离。
• 行拖拽不改 data：onRowDragEnd 只回报落点，界面顺序要变必须自己把 e.nextData（或后端返回的新序）写回 data，否则拖完会弹回原位。
• 拖拽排序和列排序（enableSorting）同开没有意义：列排序下可见顺序 ≠ 存储顺序，拖出来的相对位置对后端是错的。要拖就把 enableSorting 关掉（或至少清空 sorting）。同理，筛选态下拖拽只在可见行之间表达相对位置。
• 拖拽 id 就是行 id：不传 getRowId 时行 id 是数组下标，回调里的 activeId/overId 也就只是下标。要把 id 直接甩给后端，必须传 getRowId={(r) => r.id}。
• dragHandle="row" 与 onRowClick 同开时，键盘 <kbd>Space</kbd> 归 dnd-kit（抓起/放下），行点击只保留 <kbd>Enter</kbd>；指针端靠 6px 距离阈值区分点击与拖拽。要完全零冲突就用默认的 "cell"。
• 拖拽与 virtual 同开不推荐：视口外的行没有挂载，拖到列表边缘时既无落点也不会自动翻页。
• 组合原语没有排序 / 分页 / 冻结列 / 虚拟滚动 —— 它只是皮肤。需要这些能力就回高层 Table，不要在原语上手搓一套。
• 原语的 striped 默认 false（与高层 Table 相反）：手写结构里常有整宽附属行与跨行合并，斑马纹按 <tr> 计数，会把「一条记录」的视觉分组读乱。确实是规整的一行一条时再显式开。
• 树形（getSubRows）下只有顶层行可拖，子行手柄恒禁用——跨层级拖拽的落点语义未定义，需要拖子节点请用 Tree 或按层级拆表。

相关

Book3D · ProTable · PricingTable · JsonViewer · EditableTable · List