Element Component Pro

基于 Element UI 的二次封装组件库，参考 VbenAdmin 的 Ant Design 版本，提供 Pro 系列增强组件。

技术栈

• Vue 2.7 - 支持 Composition API 和 <script setup> 语法糖
• TypeScript - 完整类型支持
• Element UI - 基础 UI 组件

组件列表

| 组件 | 说明 | |------|------| | ProTable | 增强表格，集成搜索、工具栏、分页 | | ProForm | Schema 驱动的表单，支持栅格布局 | | ProCard | 卡片容器 | | ProDescriptions | 详情描述列表 |

安装

npm install element-component-pro element-ui vue

使用

全局注册

import Vue from 'vue'
import ElementUI from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'
import ElementComponentPro from 'element-component-pro'

Vue.use(ElementUI)
Vue.use(ElementComponentPro)

按需引入

<script setup lang="ts">
import { ProTable, ProForm } from 'element-component-pro'
</script>

<template>
  <ProTable :columns="columns" :request="fetchData" />
</template>

ProTable

<template>
  <ProTable
    :columns="columns"
    :api="fetchTableData"
    row-key="id"
    :pagination="{ pageSize: 10 }"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ProTable } from 'element-component-pro'
import type { ProColumn } from 'element-component-pro'

const columns: ProColumn[] = [
  { title: 'ID', dataIndex: 'id', width: 80, valueType: 'index' },
  { title: '姓名', dataIndex: 'name', width: 120 },
  {
    title: '状态',
    dataIndex: 'status',
    valueType: 'select',
    valueEnum: { 1: { text: '启用' }, 0: { text: '禁用' } },
  },
]

const fetchTableData = async (params) => {
  const res = await api.getList(params)
  // ProTable 约定返回 { list, total }，与 VbenAdmin 一致
  return { list: res.list, total: res.total }
}
</script>

ProTable + useProTable（tableAction）

参考 VbenAdmin 的 useTable，ProTable 提供 useProTable Hook，对外暴露 tableAction 方法。可选传入 props：useProTable(props) 支持传入 ProTableProps 或 Ref<ProTableProps>，会在表格 @register 时通过 setProps 应用，且 props 为响应式时变更会自动同步到表格（类型 UseProTablePropsReactive）。

<template>
  <ProTable
    @register="registerTable"
    title="用户列表"
    :columns="columns"
    :api="fetchTableData"
    row-key="id"
    :row-selection="{ type: 'checkbox' }"
  />
</template>

<script setup lang="ts">
import { ProTable, useProTable } from 'element-component-pro'
import type { ProColumn, TableActionType } from 'element-component-pro'

const columns: ProColumn[] = [
  { title: 'ID', dataIndex: 'id', width: 80 },
  { title: '姓名', dataIndex: 'name', width: 120 },
  { title: '年龄', dataIndex: 'age', width: 80 },
]

const [registerTable, tableAction] = useProTable()

const reload = () => {
  // 支持传入 page / pageSize / searchInfo，与 VbenAdmin 对齐
  tableAction.reload({ page: 1 })
}
</script>

TableActionType 常用方法（与 VbenAdmin BasicTable 对齐）：

| 方法 | 说明 | |------|------| | setProps | 动态更新 ProTable Props，例如列配置、分页配置等 | | reload(opt?: FetchParams) | 重新请求数据，支持指定页码、每页条数、搜索参数 | | setLoading(loading: boolean) | 手动切换表格 loading 状态 | | getDataSource() / setTableData(data) | 获取 / 设置当前表格数据 | | getRawDataSource() | 获取接口原始返回数据（未经过 afterFetch） | | getColumns() / setColumns(cols) | 获取 / 设置列配置，支持传 ProColumn[] 或列 key 数组 | | setPagination(info) | 设置分页信息（page、pageSize、total） | | getSelectRowKeys() / getSelectRows() | 获取当前选中行的 keys / 行数据 | | getRowSelection() | 获取当前行选择配置（rowSelection） | | setSelectedRowKeys(keys) / clearSelectedRowKeys() | 设置 / 清空选中行 | | deleteSelectRowByKey(key) | 取消勾选指定 key 的行 | | updateTableDataRecord(rowKey, record) | 按 rowKey 更新某一行（局部刷新，不重新请求接口） | | deleteTableDataRecord(rowKey) | 按 rowKey 删除行（支持单个或数组） | | insertTableDataRecord(record, index?) | 在指定位置插入一行数据 | | getPaginationRef() | 获取当前分页信息 { page, pageSize, total } | | getShowPagination() / setShowPagination(show) | 获取 / 设置是否显示分页 | | expandAll() / collapseAll() | 展开 / 折叠树形表格所有行 |

ProTable 操作列 + TableAction 组件

参考 VbenAdmin 的 TableAction，ProTable 提供了独立的 TableAction 组件，用于快速渲染「编辑 / 删除 / 更多」等操作按钮。

<template>
  <ProTable
    title="操作列示例"
    :columns="columns"
    :data-source="data"
    :action-column="{ title: 'Action', dataIndex: 'action', width: 220, fixed: 'right' }"
  >
    <template #bodyCell="{ column, record }">
      <!-- 只处理 action 列，其它列仍按默认方式渲染（与 Vben bodyCell 行为一致） -->
      <template v-if="column.dataIndex === 'action'">
        <TableAction
          :actions="[
            {
              label: '编辑',
              onClick: () => handleEdit(record),
            },
          ]"
          :drop-down-actions="[
            {
              label: '删除',
              color: 'error',
              popConfirm: {
                title: '确认删除该行？',
                confirm: () => handleDelete(record),
              },
            },
          ]"
        />
      </template>
    </template>
  </ProTable>
</template>

<script setup lang="ts">
import { ProTable, TableAction } from 'element-component-pro'
import type { ProColumn } from 'element-component-pro'

const columns: ProColumn[] = [
  { title: '姓名', dataIndex: 'name', width: 120 },
  { title: '年龄', dataIndex: 'age', width: 80 },
  { title: '地址', dataIndex: 'address', minWidth: 200 },
]

const data = [
  { id: 1, name: '张三', age: 28, address: '北京市朝阳区' },
  { id: 2, name: '李四', age: 32, address: '上海市浦东新区' },
]

const handleEdit = (record: Record<string, unknown>) => {
  console.log('编辑', record)
}
const handleDelete = (record: Record<string, unknown>) => {
  console.log('删除', record)
}
</script>

TableActionItem 支持的字段（与 VbenAdmin ActionItem 对齐）：

• label：按钮文本
• icon：图标 class（可传 Element UI 图标或自定义 iconfont）
• color：success / error / warning，内部映射为对应按钮类型
• type：直接透传给 el-button 的 type
• props：额外的按钮 props
• disabled：是否禁用
• divider：是否在该操作后显示分隔线
• ifShow：是否显示当前操作项（支持函数）
• tooltip：字符串或 Tooltip 配置对象
• popConfirm：气泡确认配置 { title, okText, cancelText, confirm, cancel }
• onClick：点击回调

ProForm

参考 Vben Admin Form，支持 Schema 驱动、useForm、render/slot、动态显示等。

基础用法

<template>
  <ProForm
    :schemas="schemas"
    :initial-values="{ name: '' }"
    :base-col-props="{ span: 8 }"
    @submit="handleSubmit"
  />
</template>

<script setup lang="ts">
import { ProForm } from 'element-component-pro'
import type { ProFormSchema } from 'element-component-pro'

const schemas: ProFormSchema[] = [
  { field: 'name', label: '姓名', component: 'input', required: true, colProps: { span: 8 } },
  {
    field: 'status',
    label: '状态',
    component: 'select',
    componentProps: {
      options: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 },
      ],
    },
    colProps: { span: 8 },
  },
]

const handleSubmit = (values) => {
  console.log(values)
}
</script>

useForm 方式（参考 Vben Admin）

<template>
  <ProForm @register="register" @submit="handleSubmit" />
</template>

<script setup lang="ts">
import { ProForm, useForm } from 'element-component-pro'

const [register, formActions] = useForm({
  schemas: [...],
  labelWidth: '120px',
  actionColOptions: { span: 24 },
})

// 支持 ref/computed 响应式 props
const formProps = ref({ schemas: [...] })
const [register2] = useForm(formProps)

const handleSubmit = (values) => {
  console.log(values)
}
</script>

useForm 方法（与 Vben Admin 对齐）：

| 方法 | 说明 | |------|------| | getFieldsValue | 获取表单值 | | setFieldsValue | 设置表单字段值 | | resetFields | 重置表单 | | validate | 校验整个表单 | | validateFields | 校验指定表单项 | | submit | 提交表单 | | scrollToField | 滚动到对应字段 | | clearValidate | 清空校验 | | updateSchema | 更新 schema | | appendSchemaByField | 插入 schema | | removeSchemaByField | 删除 schema | | setProps | 设置表单 Props |

Schema 高级特性

• render: 自定义渲染
• slot: 使用具名插槽自定义
• ifShow / show: 动态显示（ifShow 不渲染 DOM）
• dynamicDisabled: 动态禁用
• dynamicRules: 动态校验规则
• labelWidth: 支持字段级标签宽度，覆盖表单级 labelWidth
• v-model: 支持 modelValue 双向绑定，initialValues 仅补齐缺失字段
• useForm + v-model: 编程式 setFieldsValue/resetFields 与受控 modelValue 保持同步
• componentProps: 支持函数，可获取 formModel、formActionType

示例与文档

• 示例：运行 npm run dev 后访问开发预览，包含 ProTable、ProForm、componentSettings 测试等示例
• ProTable 文档：docs/ProTable.md
• ProForm 文档：docs/ProForm.md
• 组件默认配置：docs/ComponentSetting.md（useComponentSetting）

开发

# 安装依赖
npm install

# 开发预览
npm run dev

# 构建
npm run build

License

MIT