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>）。

禁忌 / 坑

• 列宽只认显式写在 ColumnDef 上的 size/minSize/maxSize。没写 size 的列不会落宽度样式（保持内容自适应）——这是刻意的：TanStack 会把 defaultColumn（size 150）合并进每个 columnDef，照着 getSize() 无脑出宽度会把整张表钉成等宽。
• 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 也就无从体现。
• 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 同开不推荐：视口外的行没有挂载，拖到列表边缘时既无落点也不会自动翻页。
• 树形（getSubRows）下只有顶层行可拖，子行手柄恒禁用——跨层级拖拽的落点语义未定义，需要拖子节点请用 Tree 或按层级拆表。

相关

Book3D · ProTable · PricingTable · JsonViewer · EditableTable · List