---
url: /components/table.md
---
# Table 表格

表格组件：列由 `eb-table-column` 声明并注册到父表格（列组件自身不渲染 DOM），内置客户端排序、列筛选、多选 / 单选、展开行、固定列（sticky）、横向滚动、当前行高亮与空态，并支持表尾合计、加载遮罩与服务端排序，选中可经 v-model 受控，暴露排序、筛选、选中、展开等实例方法。

## 基础用法

`data` 传入行数组，`eb-table-column` 用 `prop` 绑定字段、`label` 定义表头；`border` 与 `stripe` 开启边框和斑马纹，`sortable` 让金额列出现排序箭头（点击循环升序、降序、取消）。斑马纹加在偶数行（自第 2 行起）；组件始终开启行 hover 高亮，普通行 hover 时整行变浅灰，斑马行因底色规则声明在后、hover 仍保持斑马底色，两层不互相覆盖。数据密集的列表页推荐 `stripe` + `border` 组合，行间辨识度最高。

## 树形表格

数据行带 `children` 数组即自动启用树形渲染：首列显示展开箭头与层级缩进，点击箭头或调用行展开；`default-expand-all` 默认展开全部，`tree-props` 可自定义 children 字段名。

## 插槽列自定义单元格

在列内写 `#default` 作用域插槽即可完全接管单元格（scope 含 `row`、`$index`、`column`）；`show-overflow-tooltip` 让超宽文本省略并以 title 提示全文。

## 排序与格式化

`default-sort` 指定初始排序（立即生效，非仅高亮箭头）；`sort-method` 提供自定义比较函数（返回值自动乘以排序方向），`sort-change` 返回 `{ prop, order, column }` 用于对接后端；`formatter` 把原始值格式化为展示文本。

## 服务端排序

列设 `sortable="custom"` 后点击箭头不在本地重排，只触发 `sort-change` 携带目标排序，由页面请求或重排数据后再传入；箭头状态仍在本地维护，适合分页与大数据量场景。本例在事件回调里模拟服务端返回。

## 横向滚动

`scroll-x` 声明表格总宽（数字按 px，也可传 `max-content` 由内容撑开）：列宽合计超出容器时表体出现横向滚动条，表头随之同步偏移，`fixed` 列保持吸附；列声明了 `min-width` 时按该宽度保底、不被压缩。未传时列宽自适应容器，行为不变。

## 多选

`type="selection"` 声明多选列，表头出现全选框（含半选态）；`selectable` 可禁用指定行（本例仅已支付行可选）。选中项通过 `selection-change` 同步，也可用 `v-model:selection` 受控（传行数组回填，翻页后按 rowKey 回显），或用实例方法 `clearSelection` 清空。

## 单选

`selection-type="radio"` 把选择列换成单选框：选中即唯一值，重复点击不变更，表头不再渲染全选框。此时受控值 `v-model:selection` 为单个 key（需配合 `row-key`，未选中为 null；传行对象或单元素数组也可回显），`selection-change` 仍发单元素数组。

## 展开行

`type="expand"` 声明展开列，默认插槽渲染在展开的附加行中（scope 为 `{ row, $index }`）；配合 `default-expand-all` 或 `expand-row-keys`（需 rowKey）可默认展开。展开态变化统一经 `expand-change` 上报 `(expandedKeys, row, expanded)`：expandedKeys 为当前全部展开 key（设 rowKey 时为业务 key），平铺展开列与树形行共用同一签名。

## 空态

数据为空时渲染空态区域，默认文案为内置国际化「暂无数据」，可用 `empty-text` 修改，或用 `#empty` 插槽整体替换（可搭配 eb-empty）。

## 加载中

`loading` 为真时表体覆盖半透明遮罩并显示旋转指示，阻断数据区交互；适合远程拉取数据期间开启、结束后关闭。遮罩只盖住表体（含表尾合计），表头保持可见。

## 虚拟滚动

`virtual` 开启后万级行只渲染可视窗口，表头 / 列宽 / 固定列 / 多选 / 键盘导航全量保留。需配合 `height` 或 `maxHeight` 形成滚动视口；`row-height` 需与实际行高一致（受 size 与内容换行影响时显式对齐）。展开行与树形层级不参与虚拟模式。

## 行内编辑

列设置 `editable` 后，单元格点击进入编辑：Enter 或失焦提交、Esc 取消；提交时更新行数据并触发 `cell-change`（携带 row / prop / value / oldValue / $index），在其中做校验或落库。需要复杂编辑器（选择器、日期等）时用 default 插槽自行承载，插槽列不受 editable 影响。

## API