el-table-vue
v2.0.1
Published
对 Element-UI 的 el-table 进行二次封装,提供类似 antd Design Table 的 columns 配置方式,支持 JSX 和 scoped slots 自定义渲染
Maintainers
Readme
el-table-vue
对 Element-UI 的 el-table 进行二次封装,提供类似 antd Design Table 的 columns 配置方式。 支持多级表头、JSX 渲染、scoped slots、前端/后端分页。
特性
- ✅ 声明式 columns 配置 — 与 antd Design Table columns 用法一致,支持递归嵌套
- ✅ JSX 支持 — render 函数可直接返回 JSX,写法简洁直观
- ✅ Scoped slots — 通过插槽自定义任意列内容,支持任意嵌套层级
- ✅ 属性透传 —
v-bind="$attrs"自动透传 el-table 属性,官方扩展无需改代码 - ✅ 事件透传 —
v-on="$listeners"自动透传所有 el-table 事件 - ✅ column 属性透传 —
v-bind="columnAttrs"将 column 配置中所有 el-table-column 属性自动透传 - ✅ 多级表头 —
children字段递归嵌套,无层级限制 - ✅ 内容溢出省略 — 原生支持
show-overflow-tooltip,纯文本列自动生效 - ✅ 前端/后端分页 —
asyncPage一键切换 - ✅ Vue 2.x — 适配 Element-UI Vue 2 版本
版本说明
| 版本 | 技术栈 | 分支 |
|------|--------|------|
| 3.x | Vue 3 + Element Plus + TypeScript | vue3 |
| 2.x | Vue 2 + Element UI + JavaScript | vue2 |
如需指定版本:npm install el-table-vue@2 -S。
安装
npm install el-table-vue@2 -S前置依赖:
vue(>=2.5) +element-ui(>=2.0)。两者为 peerDependencies,需在项目中自行安装。
注册
// main.js
import Vue from "vue";
import ElementUI from "element-ui";
import "element-ui/lib/theme-chalk/index.css";
import ElTableVue from "el-table-vue";
Vue.use(ElementUI);
Vue.use(ElTableVue);按需引入时需确保 Table、TableColumn、Pagination、Loading 已注册。
快速开始
<template>
<ElTableVue
:data="tableData"
:columns="columns"
:total="total"
:currentPage="page"
:asyncPage="true"
@onChange="handlePageChange"
>
<!-- scoped slot 优先级最高,会覆盖 column.render -->
<template #rate="{ text }">
<el-rate :value="text" disabled />
</template>
</ElTableVue>
</template>
<script>
// columns.js / columns.jsx — 列配置独立文件
const columns = (vm) => [
{ prop: "id", label: "序号", width: 80 },
{ prop: "name", label: "姓名", align: "center" },
{
prop: "rate",
label: "用户信用度",
minWidth: 200,
sortable: true,
// render 支持 JSX 或 h() 两种写法
// render: (h, text) => <el-rate value={text} disabled />,
},
{
prop: "action",
label: "操作",
minWidth: 150,
fixed: "right",
render: (h, _text, record) => (
<div>
<el-button size="mini" type="danger" onClick={() => vm.toDel(record)}>删除</el-button>
<el-button size="mini" onClick={() => vm.toEdit(record)}>编辑</el-button>
</div>
),
},
];
export default {
data() {
return {
columns: [],
tableData: [],
total: 0,
page: 1,
};
},
created() {
// 传入组件实例 vm,render 函数通过闭包访问 vm 的方法
this.columns = columns(this);
},
methods: {
handlePageChange(page, pageSize) {
this.page = page;
},
toDel(record) { /* 删除逻辑 */ },
toEdit(record) { /* 编辑逻辑 */ },
},
};
</script>Columns 配置
每个 column 配置项的属性分成两类:
ElTableVue 内部属性
| 属性 | 类型 | 说明 |
|------|------|------|
| prop | string | 对应数据字段名 |
| label / title | string | 列头显示文字 |
| hAlign | string | 表头对齐方式(会自动转为 header-align) |
| className | string | 列的 className |
| render | function | 自定义渲染函数 (h, text, record, index, column) => VNode |
| customRender | function | render 的别名,兼容 antd |
| formatter | function | 格式化函数 (row, column, cellValue, index) => string |
| slot | string | 指定 scoped slot 名称(不设时默认用 prop 匹配) |
| children | array | 子列配置,用于多级表头 |
以上属性在内部处理后不会传给 el-table-column,其余属性全部透传。
透传属性(直接传给 el-table-column)
所有 el-table-column 的原生属性都支持,直接在 column 对象中声明即可,支持驼峰或 kebab-case 两种写法:
| 属性 | 写法示例 | 说明 |
|------|---------|------|
| sortable | sortable: true | 是否可排序 |
| align | align: "center" | 内容对齐 |
| width | width: 200 | 固定列宽 |
| minWidth | minWidth: 100 | 最小列宽 |
| fixed | fixed: "right" | 列固定 |
| type | type: "selection" | 列类型 |
| columnKey | columnKey: "myCol" | 列唯一标识 |
| renderHeader | "render-header": fn | 自定义列头渲染 |
| showOverflowTooltip | "show-overflow-tooltip": true | 溢出省略号 + tooltip |
| sortMethod | sortMethod: fn | 自定义排序方法 |
| ... | 其他 el-table-column 属性均可 | 官方未来新增属性无需改代码 |
// 示例:多种属性混用
columns: [
{ prop: "name", label: "姓名", align: "left", width: 120 },
{ type: "selection", width: 55 },
{
prop: "address",
label: "地址",
width: 200,
"show-overflow-tooltip": true, // kebab-case 写法
"render-header": (h) => <span>地址</span>, // JSX 自定义表头
},
]三种渲染方式(优先级从高到低)
方式一:Scoped slot(优先级最高)
在 <ElTableVue> 上通过具名插槽自定义,slot 名匹配 column.prop:
<ElTableVue :data="data" :columns="columns">
<template #rate="{ text, record, index }">
<el-rate :value="text" disabled show-score />
</template>
</ElTableVue>scoped slot 会递归转发到所有嵌套层级的 headCol,无论列在 columns 的哪一层都能生效。
方式二:render 函数(支持 JSX)
{
prop: "rate",
label: "评分",
render: (h, text, record, index, column) => {
// text = record[column.prop],当前单元格的值
// 方案 A:createElement
return h("el-rate", { props: { value: text, disabled: true } });
// 方案 B:JSX(需 babel-plugin-transform-vue-jsx)
// return <el-rate value={text} disabled />;
},
}render 参数:
| 参数 | 说明 |
|------|------|
| h | Vue createElement 函数,JSX 编译后使用 |
| text | 当前单元格值 record[column.prop] |
| record | 当前行完整数据 |
| index | 行索引 |
| column | 列配置对象 |
方式三:formatter(纯文本格式化)
{
prop: "date",
label: "日期",
formatter: (row, column, cellValue, index) => {
return cellValue ? cellValue.replace(/-/g, "/") : "-";
},
}渲染优先级
scoped slot > column.render > column.formatter > 默认取值(prop)Props
数据与列
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| data | Array | [] | 表格数据源 |
| columns | Array | [] | 列配置数组 |
| rowKey | String / Function | "id" | 行唯一标识,支持 "id" 或 (row) => row.uid |
表格外观
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| height | Number / String | - | 表格高度,超出滚动 |
| maxHeight | Number / String | - | 表格最大高度 |
| size | String | "medium" | medium / small / mini |
| stripe | Boolean | false | 斑马纹 |
| border | Boolean | false | 边框 |
| loading | Boolean | false | 加载状态 |
分页
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| total | Number | - | 数据总条数 |
| currentPage | Number | 1 | 当前页码 |
| pageSize | Number | 10 | 每页条数 |
| pageSizes | Array | [10,20,50,100] | 可选每页条数 |
| asyncPage | Boolean | false | true = 前端分页,false = 后端分页 |
| notPage | Boolean | false | 完全隐藏分页器 |
| noPage | Boolean | false | 仅一页时隐藏分页器 |
| pagination | Object | - | 自定义分页 { component: YourPagination } |
| doLayout | Boolean | false | 数据变化后调用 doLayout() 重排 |
$attrs 透传
所有 未在 ElTableVue props 中声明的属性,通过 v-bind="$attrs" 自动透传给 el-table。例如:
<!-- 这些 el-table 原生属性无需在 ElTableVue 中声明,自动生效 -->
<ElTableVue
:highlight-current-row="true"
:default-sort="{ prop: 'date', order: 'descending' }"
tooltip-effect="dark"
/>旧 API 兼容
| 属性 | 说明 |
|------|------|
| selectionChange | @deprecated 使用 @selection-change 事件替代 |
| dolayout | @deprecated 使用 doLayout 替代 |
Events
ElTableVue 特有事件
| 事件名 | 参数 | 说明 |
|--------|------|------|
| onChange | (page, pageSize) | 页码或每页条数变化 |
el-table 透传事件(v-on="$listeners" 自动透传)
| 事件名 | 参数 | 说明 |
|--------|------|------|
| select | (selection, row) | 勾选某行 |
| select-all | (selection) | 全选 |
| selection-change | (selection) | 选中变化 |
| sort-change | ({ column, prop, order }) | 排序变化 |
| filter-change | (filters) | 筛选变化 |
| row-click | (row, column, event) | 行点击 |
| row-dblclick | (row, column, event) | 行双击 |
| header-click | (column, event) | 表头点击 |
| cell-click | (row, column, cell, event) | 单元格点击 |
| cell-dblclick | (row, column, cell, event) | 单元格双击 |
| cell-mouse-enter | (row, column, cell, event) | 鼠标进入单元格 |
| cell-mouse-leave | (row, column, cell, event) | 鼠标离开单元格 |
所有 el-table 原生事件均支持,无需在 ElTableVue 中逐个声明。
Slots
| 插槽名 | 作用域 | 说明 |
|--------|--------|------|
| empty | - | 数据为空时的占位内容 |
| append | - | 表格底部追加内容 |
| pagination | { total, currentPage, pageSize, pageSizes, onSizeChange, onCurrentChange } | 自定义分页器(scoped slot),见下文「分页插槽使用方法」 |
| [column.prop] | { text, record, index, column } | 自定义列内容(scoped slot) |
分页插槽使用方法
ElTableVue 提供三种分页方式,优先级从高到低:
#pagination 作用域插槽 > pagination.component 自定义组件 > 内置分页器方式一:#pagination 作用域插槽(推荐)
通过作用域插槽完全自定义分页器的外观与布局,分页状态维护和事件处理由组件内部完成:
<ElTableVue
:data="tableData"
:columns="columns"
:total="total"
:currentPage="page"
:pageSize="size"
@onChange="handlePageChange"
>
<template #pagination="{ total, currentPage, pageSize, pageSizes, onSizeChange, onCurrentChange }">
<el-pagination
style="margin-top: 10px"
background
layout="total, sizes, prev, pager, next, jumper"
:total="total"
:current-page="currentPage"
:page-size="pageSize"
:page-sizes="pageSizes"
@size-change="onSizeChange"
@current-change="onCurrentChange"
/>
</template>
</ElTableVue>作用域参数:
| 参数 | 类型 | 说明 |
|------|------|------|
| total | Number | 数据总条数(来自 total prop) |
| currentPage | Number | 当前页码(组件内部维护,随翻页自动更新) |
| pageSize | Number | 每页条数(组件内部维护,随切换自动更新) |
| pageSizes | Array | 可选每页条数(来自 pageSizes prop) |
| onSizeChange | (size) => void | 每页条数切换回调,内部已同步状态并触发 onChange 事件 |
| onCurrentChange | (page) => void | 翻页回调,内部已同步状态并触发 onChange 事件 |
父组件只需把回调绑定到自己的分页 UI 上,无需手动处理状态:
- 后端分页(
asyncPage: false):翻页后触发onChange(page, pageSize),父组件在回调中请求新数据;- 前端分页(
asyncPage: true):组件自动截取当前页数据,同时仍会触发onChange事件。
方式二:pagination.component 自定义组件
<ElTableVue :data="data" :columns="columns" :total="total" :pagination="{ component: MyPagination }" />组件按 pagination.component 直接渲染自定义组件,分页状态由该组件自行管理,适合与业务耦合较深的分页场景。
方式三:内置分页器(默认)
不提供 pagination 插槽和 pagination prop 时自动渲染内置分页器:
<!-- total > 0 时自动出现分页器 -->
<ElTableVue :data="data" :columns="columns" :total="total" @onChange="handlePageChange" />notPage: true— 完全隐藏分页器noPage: true— 仅一页时隐藏分页器
进阶用法
columns(vm) 模式
推荐将列配置抽到独立 .js / .jsx 文件,通过参数传入组件实例:
// columns.jsx
export const columns = (vm) => [
{
prop: "action",
label: "操作",
render: (h, _text, record) => (
// vm 通过闭包捕获,可访问 methods / data
<el-button onClick={() => vm.toDel(record)}>删除</el-button>
),
},
];
// App.vue
this.columns = columns(this); // 传入当前组件实例JSX 配置
需要在项目中安装:
npm i babel-plugin-transform-vue-jsx babel-plugin-syntax-jsx babel-helper-vue-jsx-merge-props -D.babelrc:
{
"plugins": ["transform-vue-jsx"]
}内容溢出省略号
纯文本列配合固定宽度 + show-overflow-tooltip:
{ prop: "address", label: "地址", width: 200, "show-overflow-tooltip": true }headCol 内部对
formatter和默认文本使用<span class="cell-text">(内置text-overflow: ellipsis),确保省略号正确生效。
多级表头
columns: [
{ prop: "id", label: "序号" },
{
label: "配送信息",
children: [
{ prop: "name", label: "姓名" },
{
label: "地址",
children: [
{ prop: "province", label: "省" },
{ prop: "city", label: "市" },
],
},
],
},
]架构设计
ElTableVue (el-table wrapper)
│ v-bind="$attrs" → 透传 el-table 属性
│ v-on="$listeners" → 透传 el-table 事件
│ inheritAttrs: false → 避免 $attrs 污染根 div
│
└── headCol (递归列组件)
│ v-bind="columnAttrs" → 透传 el-table-column 属性
│ hasScopedSlot() → 检查 scoped slot 是否存在
│ 递归转发 $scopedSlots → 保证嵌套层级 scoped slot 生效
│
└── cellRender (函数式组件)
render(h, text, record, index, column) → 调用用户 render 函数本地开发
环境要求
- Node.js >= 6.0.0,npm >= 3.0.0(项目为 Vue 2 + webpack 3 老工具链,建议使用与项目配套的 Node 版本;单元测试已验证可在新版 Node 上运行)
- yarn 或 npm 任选其一
目录结构
el-table-vue
├── src
│ ├── myPlugin/ # 插件源码(发布内容)
│ │ ├── index.js # 插件入口
│ │ └── ELTable/
│ │ ├── elTable.vue # 主组件(表格 + 分页)
│ │ ├── headCol.vue # 递归列组件(多级表头 / 插槽转发)
│ │ └── cellRender.vue # 单元格渲染(函数式组件)
│ ├── App.vue # 本地调试 demo 页面
│ └── views/ # demo 页面(columns 配置示例)
├── tests/ # 单元测试(Jest 26 + @vue/test-utils)
├── build/ # webpack 构建配置(demo)
└── config/ # 开发环境配置安装依赖
yarn install # 或 npm install启动本地调试服务
npm run dev # 启动 webpack-dev-server,浏览器打开 http://localhost:8080运行单元测试
npm test # Jest 26 单次运行全部用例
npm test -- --watch # 监听模式,保存即重跑
npm test -- --coverage # 生成覆盖率报告(输出到 coverage/ 目录)构建 demo
npm run build # 构建 demo 页面到 dist/(dist 不入 git、不入 npm 包)发布流程
npm pack --dry-run # 预览即将发布的文件清单
npm publish # 正式发布到 npm发布内容由 package.json 的
files字段控制(LICENSE、README.md、src/myPlugin/),测试、demo、构建配置均不会进入 npm 包。
License
ISC
