EP-Comp 组件库

基于 Element Plus 的高级组件库，提供更便捷的表单构建、组件管理和装饰器功能。

特性

• 🎯 声明式表单：通过装饰器和工具函数快速构建表单
• 📱 响应式栅格：支持灵活的栅格布局
• ⚡ 异步渲染：支持自定义渲染函数
• 🔧 组件映射：灵活的组件注册和管理
• 🎨 类型安全：完整的 TypeScript 支持
• 🎭 装饰器支持：通过装饰器声明式配置组件

安装

npm install @gx-web/ep-comp

装饰器

模型装饰器

| 装饰器 | 描述 | | ----------------------------------- | -------------------- | | @EPTableColumnConfig(config) | 标记属性为表格列配置 | | @EPFormItemConfig(config) | 标记属性为表单项配置 | | @EPDescriptionsConfig(config) | 标记类为描述列表配置 | | @EPDescriptionsItemConfig(config) | 标记属性为描述项配置 |

装饰器使用示例

import {
  EPTableColumnConfig,
  EPFormItemConfig,
  FieldName,
  generateTableColumns,
  getEPFormItems
} from '@gx-web/ep-comp'

class User {
  @FieldName('用户名')
  name!: string

  @EPTableColumnConfig({ label: '用户 ID', sort: 1 })
  @EPFormItemConfig({ type: 'input', required: true })
  userId!: number

  @EPTableColumnConfig({ hide: true })
  password!: string
}

// 生成表格列配置
const columns = generateTableColumns(User, ['name', { prop: 'userId', width: 120 }, 'password'])

// 获取表单项配置
const items = getEPFormItems(User)

工具函数

模型工具函数

| 函数 | 描述 | | ---------------------------------------------------- | ----------------------------------------- | | generateTableColumns<T>(constructor, fieldsConfig) | 生成可直接传给 GxTable 的表格列配置数组 | | getEPFormItems<T>(constructor) | 获取表单项配置数组 | | getEPDescriptions<T>(constructor) | 获取描述列表配置对象 | | getEPDescriptionsItems<T>(constructor) | 获取描述项配置数组 |

函数使用示例

import {
  fromJson,
  generateTableColumns,
  getEPFormItems,
  getEPDescriptions,
  getEPDescriptionsItems
} from '@gx-web/ep-comp'

class User {
  name!: string
  email!: string
  age!: number
}

// 实例化并获取配置
const user = fromJson(User, { name: '张三', email: '[email protected]', age: 25 })
const columns = generateTableColumns(User, ['name', 'email', { prop: 'age', width: 100 }])
const items = getEPFormItems(User)
const descConfig = getEPDescriptions(User)
const descItems = getEPDescriptionsItems(User)

组件使用

1. 基础表单

<template>
  <GxForm
    v-model="formData"
    :items="formItems"
    label-width="120px"
    @submit="handleSubmit"
    @cancel="handleCancel"
    @reset="handleReset"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { GxForm } from '@gx-web/ep-comp'
import type { EPFormItemConfigType } from '@gx-web/ep-comp'

const formData = ref({
  username: '',
  email: '',
  age: 18
})

const formItems: EPFormItemConfigType<any>[] = [
  {
    prop: 'username',
    label: '用户名',
    type: 'input',
    required: true,
    props: {
      placeholder: '请输入用户名'
    }
  },
  {
    prop: 'email',
    label: '邮箱',
    type: 'input',
    required: true,
    props: {
      placeholder: '请输入邮箱',
      type: 'email'
    }
  },
  {
    prop: 'age',
    label: '年龄',
    type: 'number',
    props: {
      min: 0,
      max: 120
    }
  }
]

const handleSubmit = (data: any) => {
  console.log('表单确认:', data)
}

const handleCancel = () => {
  console.log('表单取消')
}

const handleReset = () => {
  console.log('表单重置')
}
</script>

默认情况下，GxForm 渲染“取消 / 确认”按钮；当显式开启 showReset 时，按“取消 / 重置 / 确认”的顺序渲染。cancel 仅发出取消事件，不会隐式关闭 GxDialog 或修改外部状态。

2. 使用 generateTableColumns + GxTable

<template>
  <GxTable :data="users" :columns="columns">
    <template #table-column-email="{ row }">
      <span>{{ row.email }}</span>
    </template>
  </GxTable>

  <GxForm v-model="formData" :items="formItems" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { BaseModel } from '@gx-web/core'
import {
  EPFormItemConfig,
  FieldName,
  generateTableColumns,
  getEPFormItems,
  GxForm,
  GxTable
} from '@gx-web/ep-comp'

class User extends BaseModel {
  @FieldName('用户名')
  name!: string

  @FieldName('邮箱')
  @EPFormItemConfig({ type: 'input', required: true })
  email!: string
}

const users = ref<User[]>([])
const columns = generateTableColumns(User, ['name', { prop: 'email', minWidth: 220 }])
const formItems = getEPFormItems(User)
const formData = ref(new User())
</script>

GxTable、GxTableColumns、GxTableColumn 只负责消费显式传入的 columns 配置并完成渲染，不会根据 model、decorator 或 metadata 自动推导列定义。

3. 使用 generateTableColumns + useTablePage + GxPaginationTable

<template>
  <GxPaginationTable
    v-model:page="tablePage.page.current"
    v-model:limit="tablePage.page.size"
    :loading="tablePage.loading"
    :data="list"
    :columns="columns"
    :total="tablePage.page.total"
    @pagination="tablePage.onChange"
  >
    <template #header>
      <div>用户列表</div>
    </template>

    <template #action-bar>
      <el-button type="primary">新增用户</el-button>
    </template>
  </GxPaginationTable>
</template>

<script setup lang="ts">
import { FieldName } from '@gx-web/core'
import { useTablePage } from '@gx-web/tool'
import { GxPaginationTable, generateTableColumns } from '@gx-web/ep-comp'

class User {
  @FieldName('用户名')
  name!: string

  @FieldName('邮箱')
  email!: string
}

const columns = generateTableColumns(User, ['name', { prop: 'email', minWidth: 220 }])

const [list, tablePage] = useTablePage(async ({ current, size }) => {
  const records = await Promise.resolve([
    { name: '张三', email: '[email protected]' },
    { name: '李四', email: '[email protected]' }
  ])

  return {
    records,
    total: current * size
  }
})
</script>

GxPaginationTable 默认内置 GxTable + GxPagination。当不提供 default slot 时，会直接消费 data、columns 与 tableProps；当需要完全自定义表格区时，可通过 default slot 覆盖表格内容区，同时保留组件自身的分页布局与交互入口。

Breaking Changes

• GxForm 默认按钮从“提交 / 重置”调整为“取消 / 确认”，默认不再显示重置按钮。
• GxForm 新增 cancel 事件；取消按钮只表达取消语义，不会隐式关闭 GxDialog。
• GxSearch 不再作为 GxForm 的搜索变体维护，默认固定为“查询 / 重置”。
• GxSearch 不再提供 submit / reset / action 按钮扩展 slots；如需复杂按钮区，请改用 GxPaginationTable 的 header、action-bar 或页面外层布局。

API 参考

装饰器类型

EPTableColumnConfigType

| 属性 | 说明 | 类型 | 默认值 | | ------------ | ---------------------- | ------------------------------------- | ------ | | type | 组件类型 | ComponentKeyType | - | | props | 组件属性 | ComponentPropsMap[ComponentKeyType] | - | | prop | 字段名 | InstanceKey<T> | - | | hide | 是否隐藏 | boolean \| ((data: T[]) => boolean) | - | | label | 列名 | string | - | | width | 列的宽度 | string \| number | - | | minWidth | 列的最小宽度 | string \| number | - | | sort | 排序 | number | - | | fixed | 列是否固定在左侧或右侧 | boolean \| 'left' \| 'right' | - | | align | 列内容的对齐方式 | 'left' \| 'center' \| 'right' | - | | headerAlign | 列头内容的对齐方式 | 'left' \| 'center' \| 'right' | - | | render | 自定义列内容渲染 | (scope) => Component | - | | headerRender | 自定义列头渲染 | (scope) => Component | - |

EPFormItemConfigType

| 属性 | 说明 | 类型 | 默认值 | | -------- | -------------- | ------------------------------------- | ------ | | type | 组件类型 | ComponentKeyType | - | | props | 组件属性 | ComponentPropsMap[ComponentKeyType] | - | | prop | 字段名 | InstanceKey<T> | - | | label | 标签文本 | string | - | | required | 是否必填 | boolean | - | | rules | 验证规则 | RuleItem[] | - | | hide | 是否隐藏 | boolean \| ((form: T) => boolean) | - | | col | 栅格布局配置 | ColConfigType | - | | render | 自定义渲染函数 | (form: T) => Component | - | | sort | 排序 | number | - |

支持的组件类型

• input - 输入框
• select - 选择器
• datePicker - 日期选择器
• switch - 开关
• checkbox - 复选框
• radio - 单选框
• textarea - 文本域
• number - 数字输入框
• timePicker - 时间选择器
• cascader - 级联选择器
• upload - 上传
• slider - 滑块
• rate - 评分
• colorPicker - 颜色选择器

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 构建
pnpm build

迁移指南

从 @gx-web/core 迁移

Element-Plus 相关装饰器和工具函数已从 @gx-web/core 移至 @gx-web/ep-comp：

1. 导入路径更新：将 @gx-web/core 的 Element-Plus 相关导入改为 @gx-web/ep-comp
2. 表格调用方式调整：getEPTableItems / getEPTableColumns 统一迁移到 generateTableColumns + GxTable

// 旧写法
import { EPTableItemConfig, getEPTableItems } from '@gx-web/core'
const columns = getEPTableItems(User)

// 新写法
import { generateTableColumns } from '@gx-web/ep-comp'

const columns = generateTableColumns(User, ['name', 'email'])

Breaking Change：移除 getEPTableColumns

getEPTableColumns 已从 @gx-web/ep-comp 的实现与公开导出中删除，不再保留兼容入口。

// 旧写法（已删除）
import { getEPTableColumns } from '@gx-web/ep-comp'
const columns = getEPTableColumns(User)

// 替代写法
import { generateTableColumns, GxTable } from '@gx-web/ep-comp'

const columns = generateTableColumns(User, ['name', { prop: 'email', minWidth: 220 }])

// <GxTable :data="list" :columns="columns" />

如果原先依赖 decorator 自动提取列定义，请改为在调用侧显式传入 fieldsConfig，再把返回的 columns 交给 GxTable 渲染。

许可证

MIT