@eclou/e-table 使用说明

@eclou/e-table 是一个基于 Vue 3 + Element Plus 的 CRUD 表格组件，内置：

• 列表查询 + 分页 + 排序
• 新增/编辑弹窗
• 删除确认
• 过滤区、工具栏、操作列、表单槽位扩展

安装

npm i @eclou/e-table element-plus axios

快速开始

全局注册

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import { ETablePlugin } from '@eclou/e-table'
import 'element-plus/dist/index.css'

const app = createApp(App)
app.use(ElementPlus)
app.use(ETablePlugin)
app.mount('#app')

局部注册

<script setup lang="ts">
import { ETable } from '@eclou/e-table'
</script>

后端返回格式约定

列表请求（listUrl）默认按以下结构读取数据：

{
  "code": 0,
  "message": "ok",
  "data": {
    "count": 100,
    "page": 1,
    "data": []
  }
}

data.data 会作为表格数据，data.count 用于分页总数。

Props

名称	类型	默认值	说明
pk	string	"_id"	主键字段名，删除时会用到
page	number	1	当前版本未直接使用
row	number	10	每页条数
query	object	{}	固定查询参数，会和过滤条件合并
initFilter	object	{}	初始过滤条件
layout	string	"prev, pager, next"	分页布局，透传给 el-pagination
defualtFilter	boolean	true	是否显示默认过滤区（字段名按源码拼写）
defaultAction	boolean	true	是否显示默认操作列
defaultEdit	boolean	true	是否显示默认编辑按钮
defaultDelete	boolean	true	是否显示默认删除按钮
listUrl	string	-	列表接口地址（必填）
addUrl	string	-	新增提交地址
submitUrl	string	-	编辑提交地址
deleteUrl	string	-	删除接口地址
filterLazy	number	600	过滤防抖毫秒数
noticeFiled	string	""	删除确认文案展示字段（字段名按源码拼写）
requestMethod	object	{ addUrl:'POST', submitUrl:'POST', deleteUrl:'POST' }	各接口请求方法
formFullScreen	boolean	false	表单弹窗是否全屏
axios	AxiosInstance	null	自定义请求实例，不传则内部创建实例

组件事件（emits）

事件名	回调参数	用途
beforeFilter	(params)	列表请求前触发
afterFilter	(res, setItems)	列表成功后触发，可二次处理列表
beforeAdd	(form, setForm)	打开新增弹窗前初始化表单
beforeEdit	(form, setForm)	打开编辑弹窗前处理表单
beforeSubmit	(submitForm, next)	提交前改写数据或中断提交
afterSubmit	(errors)	提交后触发（成功/失败都会触发）
afterDelete	(data, success)	删除请求完成后触发

beforeSubmit 中的 next 用法：

• next(true)：中断提交
• next(newFormObject)：替换提交数据

暴露函数与引用（defineExpose）

可通过 ref 调用：

名称	类型	说明
fetchList	() => void	手动刷新列表
submit	() => void	手动触发表单提交
clear	() => void	清空过滤并重置列表
initFormValue	(formValue) => void	批量设置表单值
items	Ref<any[]>	当前表格数据
formRef	Ref<FormInstance>	表单实例引用
TableRef	Ref<ElTable>	表格实例引用

插槽

插槽名	作用域参数	说明
默认插槽	-	放 el-table-column
filter	{ filter, add }	自定义查询区与新增按钮
toolbar	-	表格上方工具栏
action	-	整体替换操作列
actionMore	{ row, edit, delete }	默认编辑/删除按钮前插入内容
actionMoreAfter	{ row, edit, delete }	默认编辑/删除按钮后插入内容
form	{ setFormRef, form, action, errors, loading, close, submit }	自定义新增/编辑表单

使用用例

用例 1：标准 CRUD（查询 + 新增/编辑 + 删除）

<template>
  <ETable
    ref="tableRef"
    list-url="/api/user/list"
    add-url="/api/user/add"
    submit-url="/api/user/edit"
    delete-url="/api/user/delete"
    pk="id"
    notice-filed="name"
    :query="{ status: 1 }"
    :request-method="{ addUrl: 'POST', submitUrl: 'PUT', deleteUrl: 'DELETE' }"
    @before-submit="handleBeforeSubmit"
  >
    <template #filter="{ filter, add }">
      <el-form-item label="姓名">
        <el-input v-model="filter.name" placeholder="请输入姓名" />
      </el-form-item>
      <el-form-item>
        <el-button type="primary" @click="add">新增</el-button>
      </el-form-item>
    </template>

    <el-table-column prop="id" label="ID" width="80" />
    <el-table-column prop="name" label="姓名" />
    <el-table-column prop="email" label="邮箱" />

    <template #form="{ setFormRef, form, action, submit, close }">
      <el-form :model="form" :ref="setFormRef">
        <el-form-item label="姓名" prop="name" required>
          <el-input v-model="form.name" />
        </el-form-item>
        <el-form-item label="邮箱" prop="email" required>
          <el-input v-model="form.email" />
        </el-form-item>
        <el-form-item>
          <el-button type="primary" @click="submit">
            {{ action === 'add' ? '创建' : '保存' }}
          </el-button>
          <el-button @click="close">取消</el-button>
        </el-form-item>
      </el-form>
    </template>
  </ETable>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableRef = ref()

const handleBeforeSubmit = (form: Record<string, unknown>, next: (arg: unknown) => void) => {
  const payload = { ...form, updatedAt: Date.now() }
  next(payload)
}
</script>

用例 2：通过 expose 手动控制

<template>
  <div>
    <el-button @click="refresh">手动刷新</el-button>
    <el-button @click="resetTable">清空筛选</el-button>
    <ETable ref="tableRef" list-url="/api/order/list" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const tableRef = ref<{
  fetchList: () => void
  clear: () => void
}>()

const refresh = () => tableRef.value?.fetchList()
const resetTable = () => tableRef.value?.clear()
</script>

注意事项

• 当前源码字段名为 defualtFilter、noticeFiled，使用时请按该拼写传参。
• 组件会把未声明的属性通过 $attrs 透传到 el-table，可直接使用 Element Plus 的表格属性和事件。