@aspire-ui/element-component-pro

Element Component Pro

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

技术栈

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

组件列表

安装

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, ProDescriptions } 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 对齐）：

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 对齐）：

Schema 高级特性

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

{
  field: 'name',
  label: '姓名',
  component: 'input',
  tooltip: true,
}

{
  field: 'status',
  label: '状态',
  component: 'select',
  tooltip: ({ values }) => values.name ? `当前姓名：${values.name}` : '请选择状态',
}

更多说明见 docs/ProForm.md。

ProDescriptions

参考 Vben Admin Description，用于详情页信息展示，支持 schema 驱动、响应式列数、折叠以及 useDescription 编程式更新。

• tooltip: 支持字段 value 的悬浮提示，适合长文本、数组值和对象值预览

<template>
  <ProDescriptions
    title="基础示例"
    :column="3"
    :data="detailData"
    :schema="schema"
    :use-collapse="true"
    :collapse-options="{ canExpand: true }"
  />
</template>

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

const detailData = {
  username: 'test',
  nickName: 'VB',
  phone: '15695909xxx',
  email: '190848757@qq.com',
}

const schema: DescriptionSchema[] = [
  { label: '用户名', dataIndex: 'username' },
  { label: '昵称', dataIndex: 'nickName' },
  { label: '联系电话', dataIndex: 'phone' },
  { label: '邮箱', dataIndex: 'email' },
]
</script>

useDescription

<template>
  <ProDescriptions @register="register" />
</template>

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

const [register, descriptionAction] = useDescription({
  title: 'useDescription',
  data: {
    name: '张三',
    status: '启用',
  },
  schema: [
    { label: '姓名', dataIndex: 'name' },
    { label: '状态', dataIndex: 'status' },
  ],
})

const updateData = () => {
  descriptionAction.setData({ status: '禁用' })
}
</script>

示例与文档

• 示例：运行 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