Table 表格
用于展示多条结构类似的数据，支持排序、筛选、选择、展开、树形层级、合计和自定义单元格等能力。
基础表格
向 el-table 传入 data 数组，在 el-table-column 中使用 prop 对应字段名，使用 label 定义列标题。
vue
<el-table :data="tableData" style="width: 100%">
<el-table-column prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="owner" label="负责人" width="120" />
<el-table-column prop="city" label="城市" />
</el-table>斑马纹与边框
设置 stripe 可以使用斑马纹；设置 border 可以显示纵向边框。两者常用于数据密度较高的后台页面。
vue
<el-table :data="tableData" stripe border style="width: 100%">
<el-table-column prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="owner" label="负责人" width="120" />
<el-table-column prop="amount" label="报价金额" width="140" />
<el-table-column prop="status" label="状态" />
</el-table>状态行
通过 row-class-name 可以给特定行添加状态样式，用于提示风险、成功或异常数据。
vue
<template>
<el-table :data="tableData" :row-class-name="tableRowClassName">
<el-table-column prop="date" label="日期" />
<el-table-column prop="project" label="项目名称" />
<el-table-column prop="risk" label="风险等级" />
</el-table>
</template>
<script setup lang="ts">
const tableRowClassName = ({ row }: { row: { risk: string } }) => {
if (row.risk === '高') return 'warning-row'
if (row.risk === '低') return 'success-row'
return ''
}
</script>溢出提示
当单元格内容较长时，设置 show-overflow-tooltip 可以让内容保持单行，并在 hover 时展示完整内容。
vue
<el-table :data="tableData" style="width: 100%">
<el-table-column type="selection" width="48" />
<el-table-column prop="project" label="项目名称" width="200" />
<el-table-column prop="city" label="城市" width="120" />
<el-table-column prop="address" label="项目地址" show-overflow-tooltip />
</el-table>固定表头
当纵向内容较多时，设置 height 即可固定表头，让表格内容区域滚动。
vue
<el-table :data="tableLongData" height="240" style="width: 100%">
<el-table-column prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="owner" label="负责人" width="120" />
<el-table-column prop="city" label="城市" />
</el-table>固定列
横向字段较多时，可以为列设置 fixed。fixed 为 true 时固定在左侧，也可以设置为 right 固定到右侧。
vue
<el-table :data="tableWideData" style="width: 100%">
<el-table-column fixed prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="address" label="项目地址" width="360" />
<el-table-column fixed="right" label="操作" width="150">
<template #default>
<el-button link type="primary" size="small">详情</el-button>
<el-button link type="primary" size="small">编辑</el-button>
</template>
</el-table-column>
</el-table>固定列和表头
height 和 fixed 可以同时使用，适合字段多、数据多的表格。
vue
<el-table :data="tableWideData" height="240" border style="width: 100%">
<el-table-column fixed prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="address" label="项目地址" width="360" />
<el-table-column fixed="right" prop="status" label="状态" width="120" />
</el-table>流体高度
设置 max-height 后，表格会在内容超过最大高度时滚动；内容较少时会保持实际高度。
vue
<template>
<el-table :data="tableData" max-height="240">
<el-table-column fixed prop="date" label="日期" width="140" />
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column fixed="right" label="操作" width="100">
<template #default="scope">
<el-button link type="danger" size="small" @click.prevent="deleteRow(scope.$index)">
移除
</el-button>
</template>
</el-table-column>
</el-table>
</template>多级表头
把 el-table-column 嵌套在另一个 el-table-column 内即可创建多级表头。
vue
<el-table :data="tableData" border>
<el-table-column prop="date" label="日期" width="140" />
<el-table-column label="项目信息">
<el-table-column prop="project" label="项目名称" width="220" />
<el-table-column prop="owner" label="负责人" width="120" />
</el-table-column>
</el-table>单选
设置 highlight-current-row 可以高亮当前行，并通过 current-change 获取当前选中行。
vue
<template>
<el-table :data="tableData" highlight-current-row @current-change="handleCurrentChange">
<el-table-column prop="date" label="日期" />
<el-table-column prop="project" label="项目名称" />
</el-table>
</template>
<script setup lang="ts">
const handleCurrentChange = (row) => {
console.log(row)
}
</script>多选
添加 type="selection" 列即可启用多选。配合 row-key 与 reserve-selection 可以在数据刷新后保留选中项。
vue
<template>
<el-table ref="tableRef" :data="tableData" row-key="id" @selection-change="handleSelectionChange">
<el-table-column type="selection" width="48" :selectable="selectable" />
<el-table-column prop="project" label="项目名称" />
</el-table>
</template>排序
在列上设置 sortable 即可排序。使用 default-sort 可以设置默认排序列和排序顺序；后端排序时将 sortable 设置为 custom 并监听 sort-change。
vue
<el-table :data="tableData" :default-sort="{ prop: 'amountValue', order: 'descending' }">
<el-table-column prop="date" label="日期" sortable />
<el-table-column prop="project" label="项目名称" />
<el-table-column prop="amountValue" label="报价金额" sortable :formatter="formatAmount" />
</el-table>筛选
在列上设置 filters 和 filter-method 即可开启筛选。需要重置筛选时，可以调用 Table 暴露的 clearFilter 方法。
vue
<template>
<el-table ref="tableRef" row-key="id" :data="tableData">
<el-table-column
prop="status"
label="状态"
column-key="status"
:filters="statusFilters"
:filter-method="filterStatus"
/>
</el-table>
</template>自定义列模板
通过默认插槽可以自定义列内容。插槽提供 row、column、$index 和内部 store 等信息。
vue
<el-table :data="tableData">
<el-table-column label="项目">
<template #default="{ row }">
<el-tag>{{ row.project }}</el-tag>
</template>
</el-table-column>
<el-table-column label="操作">
<template #default>
<el-button link type="primary" size="small">详情</el-button>
</template>
</el-table-column>
</el-table>自定义表头
通过 header 插槽可以自定义表头内容，常用于表头搜索、提示图标或复杂标题。
vue
<el-table :data="filterTableData">
<el-table-column prop="project" label="项目名称" />
<el-table-column>
<template #header>
<el-input v-model="search" size="small" placeholder="搜索城市" />
</template>
<template #default="{ row }">{{ row.city }}</template>
</el-table-column>
</el-table>展开行
当行内容较多且不希望横向滚动时，可以设置 type="expand" 的列，将额外信息放入展开区域。
vue
<el-table :data="tableData">
<el-table-column type="expand">
<template #default="{ row }">
<div>项目地址：{{ row.address }}</div>
</template>
</el-table-column>
<el-table-column prop="project" label="项目名称" />
</el-table>树形数据
当行数据包含 children 字段时，Table 可以展示树形数据。树形表格需要设置 row-key。
vue
<el-table :data="treeData" row-key="id" border default-expand-all>
<el-table-column prop="name" label="模块" width="240" />
<el-table-column prop="owner" label="负责人" width="120" />
<el-table-column prop="status" label="状态" />
</el-table>表尾合计行
设置 show-summary 可以显示合计行。通过 summary-method 可以自定义合计逻辑和展示内容。
vue
<el-table :data="tableData" border show-summary :summary-method="getSummaries">
<el-table-column prop="name" label="费用项" />
<el-table-column prop="amount" label="金额" />
<el-table-column prop="count" label="数量" />
</el-table>合并行或列
通过 span-method 可以合并行或列。方法返回 [rowspan, colspan]，也可以返回 { rowspan, colspan }。
vue
<el-table :data="tableData" :span-method="spanMethod" border>
<el-table-column prop="category" label="类别" />
<el-table-column prop="name" label="费用项" />
<el-table-column prop="amount" label="金额" />
</el-table>自定义索引
type="index" 会展示默认行号。通过 index 属性可以设置起始值或传入方法自定义行号。
vue
<el-table :data="tableData">
<el-table-column type="index" :index="indexMethod" width="80" label="序号" />
<el-table-column prop="project" label="项目名称" />
</el-table>表格布局
通过 table-layout 可以控制表格布局方式，支持 fixed 和 auto。
vue
<el-radio-group v-model="tableLayout">
<el-radio-button value="fixed">fixed</el-radio-button>
<el-radio-button value="auto">auto</el-radio-button>
</el-radio-group>
<el-table :data="tableData" :table-layout="tableLayout">
<el-table-column prop="date" label="日期" />
<el-table-column prop="project" label="项目名称" />
</el-table>Table API
Table 属性
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| data | 表数据 | array | [] |
| height | 表格高度，设置后可固定表头 | string | number | - |
| max-height | 表格最大高度 | string | number | - |
| stripe | 是否为斑马纹表格 | boolean | false |
| border | 是否带有纵向边框 | boolean | false |
| size | 表格尺寸 | large | default | small | - |
| fit | 列宽是否自撑开 | boolean | true |
| show-header | 是否显示表头 | boolean | true |
| highlight-current-row | 是否高亮当前行 | boolean | false |
| current-row-key | 当前行的 key，只写属性 | string | number | - |
| row-class-name | 行的 className 回调或固定类名 | function | string | - |
| row-style | 行的 style 回调或固定样式 | function | object | - |
| cell-class-name | 单元格 className 回调或固定类名 | function | string | - |
| cell-style | 单元格 style 回调或固定样式 | function | object | - |
| header-cell-class-name | 表头单元格 className 回调或固定类名 | function | string | - |
| header-cell-style | 表头单元格 style 回调或固定样式 | function | object | - |
| row-key | 行数据的唯一 Key，保留选择和树形数据时必填 | function | string | - |
| empty-text | 空数据时显示的文本，也可以通过 empty 插槽设置 | string | No Data |
| default-expand-all | 是否默认展开所有行 | boolean | false |
| expand-row-keys | 当前展开行的 key 数组，需要设置 row-key | array | - |
| default-sort | 默认排序列和排序顺序 | object | - |
| tooltip-effect | 溢出 Tooltip 的主题 | dark | light | dark |
| tooltip-options | 溢出 Tooltip 的选项 | object | - |
| show-summary | 是否显示合计行 | boolean | false |
| sum-text | 合计行第一列文本 | string | Sum |
| summary-method | 自定义合计方法 | function | - |
| span-method | 合并行或列的计算方法 | function | - |
| select-on-indeterminate | 表头半选状态下点击是否全选 | boolean | true |
| indent | 树形数据缩进距离 | number | 16 |
| lazy | 是否懒加载子节点 | boolean | false |
| load | 加载子节点数据的方法 | function | - |
| tree-props | 树形数据配置 | object | { hasChildren: 'hasChildren', children: 'children' } |
| table-layout | 表格布局方式 | fixed | auto | fixed |
| scrollbar-always-on | 是否总是显示滚动条 | boolean | false |
| flexible | 是否确保主轴最小尺寸 | boolean | false |
| show-overflow-tooltip | 是否让所有列开启溢出 Tooltip | boolean | object | false |
| tooltip-formatter | 自定义溢出 Tooltip 内容 | function | - |
| preserve-expanded-content | 折叠后是否保留展开行内容 DOM | boolean | false |
| native-scrollbar | 是否使用原生滚动条样式 | boolean | false |
| row-expandable | 判断行是否允许展开 | function | - |
Table 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| select | 用户手动勾选数据行时触发 | Function |
| select-all | 用户手动勾选全选时触发 | Function |
| selection-change | 选择项发生变化时触发 | Function |
| cell-click | 单元格被点击时触发 | Function |
| row-click | 行被点击时触发 | Function |
| row-dblclick | 行被双击时触发 | Function |
| header-click | 表头被点击时触发 | Function |
| sort-change | 排序条件变化时触发 | Function |
| filter-change | 筛选条件变化时触发 | Function |
| current-change | 当前行变化时触发 | Function |
| header-dragend | 拖动表头改变列宽时触发 | Function |
| expand-change | 展开行或树形节点展开状态变化时触发 | Function |
| scroll | 表格滚动后触发 | Function |
Table 插槽
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | Table-column |
| append | 插入到表格最后一行之后的内容 | - |
| empty | 空数据时的自定义内容 | - |
Table 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| clearSelection | 清空用户选择 | Function |
| getSelectionRows | 返回当前选中的行 | Function |
| toggleRowSelection | 切换某一行的选中状态 | Function |
| toggleAllSelection | 切换全选和全不选 | Function |
| toggleRowExpansion | 切换展开行或树形行的展开状态 | Function |
| setCurrentRow | 设置当前选中行 | Function |
| clearSort | 清空排序条件 | Function |
| clearFilter | 清除指定列或全部筛选条件 | Function |
| doLayout | 对 Table 进行重新布局 | Function |
| sort | 手动排序表格 | Function |
| scrollTo | 滚动到指定坐标 | Function |
| setScrollTop | 设置垂直滚动位置 | Function |
| setScrollLeft | 设置水平滚动位置 | Function |
Table-column API
Table-column 属性
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 列类型，可选 selection、index、expand | default | selection | index | expand | default |
| index | 自定义索引，仅对 type="index" 有效 | number | function | - |
| label | 列标题 | string | - |
| column-key | 列 key，使用 filter-change 时用于标识列 | string | - |
| prop / property | 字段名称 | string | - |
| width | 列宽 | string | number | '' |
| min-width | 最小列宽，剩余宽度会按比例分配 | string | number | '' |
| fixed | 是否固定列，true 表示固定在左侧 | left | right | boolean | false |
| render-header | 自定义表头渲染方法 | function | - |
| sortable | 是否可排序，custom 表示远程排序 | boolean | string | false |
| sort-method | 自定义排序方法 | function | - |
| sort-by | 指定排序字段或排序方法 | function | string | array | - |
| sort-orders | 排序策略轮转顺序 | array | ['ascending', 'descending', null] |
| resizable | 是否可拖动改变列宽，需要 Table 设置 border | boolean | true |
| formatter | 格式化单元格内容 | function | - |
| show-overflow-tooltip | 内容过长时是否显示 Tooltip | boolean | object | undefined |
| align | 内容对齐方式 | left | center | right | left |
| header-align | 表头对齐方式，未设置时跟随 align | left | center | right | left |
| class-name | 列内容自定义类名 | string | - |
| label-class-name | 当前列标题自定义类名 | string | - |
| selectable | 决定行是否可勾选，仅对 selection 列有效 | function | - |
| reserve-selection | 数据刷新后是否保留选择，需要设置 row-key | boolean | false |
| filters | 过滤选项数组 | array | - |
| filter-placement | 过滤弹出框位置 | enum | - |
| filter-method | 数据过滤方法 | function | - |
| filter-multiple | 是否允许多选过滤 | boolean | true |
Table-column 插槽
| 插槽名 | 说明 |
|---|---|
| default | 自定义列内容，作用域包含 row、column、$index、store |
| header | 自定义表头内容，作用域包含 column、$index |
| filter-icon | 自定义过滤图标 |