# 基于Vue3+ElementPlus的低代码表单设计器

**Repository Path**: xbos1314/workfox-form-generator

## Basic Information

- **Project Name**: 基于Vue3+ElementPlus的低代码表单设计器
- **Description**: WorkfoxFormGennerator 是一个基于 Vue 3 和 Element Plus 构建的动态表单设计器与低代码表单渲染器。它提供了灵活的表单设计与渲染功能，支持表单字段的动态管理和自定义组件渲染。该项目主要面向需要自定义动态表单的开发者，支持表单设计、字段渲染、表单验证、自定义组件配置和数据交互等功能。
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: http://129.204.236.115:8090/
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2025-05-05
- **Last Updated**: 2025-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 表单设计器, 低代码

## README

# workfox-form-generator

WorkfoxFormGennerator 是一个基于 Vue 3 和 Element Plus 构建的动态表单生成与渲染库。它提供了灵活的表单设计与渲染功能，支持表单字段的动态管理和自定义组件渲染。该项目主要面向需要自定义动态表单的开发者，支持表单设计、字段渲染、表单验证和数据交互等功能。

WorkfoxFormGennerator 支持用户以 JSON 的形式配置自定义组件，用户只需通过定义组件名称（type）、标签名（label）、属性（attributes）、事件（events）等信息，即可实现组件的注册、渲染和交互逻辑，从而满足个性化的表单设计与业务扩展需求，无需修改核心代码即可灵活扩展组件体系。

## 更新日志
| 版本                    | 更新内容                     |
|------------------------|-----------------------------|
| 1.0.5                  | 渲染器添加props.disabled、选项值统一修改为数字、子表单拖入组件限制逻辑修改  |


## 项目预览
[在线预览地址](http://129.204.236.115:8090/)

## 主要功能
	1.	动态表单设计器 (Form Designer)：通过图形化界面设计表单，支持字段拖拽、表单布局自定义，方便用户快速构建表单。
	2.	表单渲染器 (Form Renderer)：通过 JSON 配置生成表单，支持动态展示设计好的表单，并且支持与后端 API 交互，获取表单数据或提交表单。
	3.	自定义字段组件：提供灵活的字段组件，支持根据业务需求自由组合自定义表单字段和组件。
	4.	表单验证：内置多种表单验证规则，支持主子表数据的统一验证，确保数据的正确性。
	5.	文件上传：支持集成文件图片上传功能，方便与后端进行文件上传操作。
	6.	高度可配置：通过传入配置 JSON，可以自由配置字段、表单样式、验证规则、从后端接口获取选项数据等。

## 技术栈
	•	Vue 3：响应式、灵活的前端框架。
	•	Element Plus：为 Vue 3 提供的 UI 组件库，提供高质量的组件支持。
	•	vuedraggable：用于表单项拖拽排序功能，增强表单交互性。
	•	quill：富文本编辑器，用于提供强大的富文本输入框。
	•	codemirror: 代码编辑器，预览表单JSON及编写事件代码
	•	axios: 发起网络请求

## 已支持的组件

更多组件请使用属性customWidgetList进行配置

### 容器组件

| 组件名     | 描述             |
|------------|------------------|
| 栅格布局   | 实现响应式布局    |
| 卡片       | 卡片式区域容器    |
| 标签页     | 多标签页切换容器  |
| Flex 行    | 灵活布局容器      |
| 子表单     | 支持嵌套子表单    |

### 表单组件

| 组件名         | 描述                 |
|----------------|----------------------|
| 输入框         | 文本输入             |
| 数字输入框     | 仅允许输入数字       |
| 选择框         | 单/多项下拉选择框     |
| 树形选择框     | 树状结构数据选择框   |
| 单选框         | 多个选项中选一个     |
| 多选框         | 多个选项中选多个     |
| 开关           | 二元状态切换         |
| 日期时间       | 日期、时间选择       |
| 图片上传       | 上传图片             |
| 文件上传       | 上传文件             |
| 评分           | 星级评分输入         |
| 富文本         | 支持图文编辑         |

单选框、多选框、树形选择框、选择框 可配置接口从后端获取数据
### 基础组件

| 组件名 | 描述       |
|--------|------------|
| 按钮   | 可配置操作按钮 |
| 标题   | 用于展示标题 |
| 文字   | 展示说明文字 |
| 提示   | 警告/提示信息 |
| 分割线 | 页面分隔线 |

## 安装与使用

可以通过 npm 安装并在 Vue 项目中使用，通过简单的 API 调用和配置，快速实现表单设计与渲染。

### 安装
```sh
npm install element-plus
npm install vuedraggable
npm install workfox-form-generator
```

### 使用
```js
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import Draggable from 'vuedraggable'

import WorkfoxFormGenerator from 'workfox-form-generator'
import 'workfox-form-generator/dist/workfox-form-generator.css'

app.component('Draggable', Draggable)
app.use(ElementPlus)
app.use(WorkfoxFormGenerator)//注册设计器FormDesigner、渲染器FormRenderer
```

```vue
<FormDesigner ref="formDesignerRef" @save="save" @close="close" :formJson="formJson" :requestHeaders="requestHeaders" :uploadApi="uploadApi" :fieldData="fieldData" :config="config" :customWidgetList="customWidgetList">
    <template #heardButtons></template>
</FormDesigner>

<FormRenderer ref="formRendererRef" :formJson="formJson" :requestHeaders="requestHeaders" :uploadApi="uploadApi" :customWidgetList="customWidgetList"/>
```

```js
const formDesignerRef = ref()// 设计器ref
const formRendererRef = ref() // 渲染器ref

// 设计器配置
const config = ref({
  showSaveButton: true,// 显示保存按钮
  showCloseButton: true,// 显示关闭按钮
  loadLocalData: true// 设计器挂载时加载本地数据
})

// 请求头
const requestHeaders = ref({
  Authorization: ''
})

// 文件图片上传地址
const uploadApi = ref('/api/upms/file/upload')

// 表单配置数据
const formJson = ref()

//字段数据
const fieldData = ref({
  "fields": [
    { "label": "字段描述", "value": "字段名称" },
  ],
  "children": [
    {
      "label": "子表描述",
      "value": "子表名称",
      "fields": [
        { "label": "字段描述", "value": "字段名称" },
      ]
    },
  ]
})

//自定义组件列表
const customWidgetList = ref([])// 请查看对应章节

// 设计器保存事件
const save = (data) => {
  console.log('保存表单设计器数据', data)
}

// 设计器关闭事件
const close = () => {
  console.log('触发关闭表单设计器事件')
}

// 异步设置设计器的表单内容
formDesignerRef.value.setFormJson(formJson.value)

// 清空设计器内容
formDesignerRef.value.resetFormJson()

// 异步设置渲染器的表单内容
formRendererRef.value.setFormJson(formJson.value)

// 获取表单填写内容，会检查填写内容是否正确，错误会抛出异常
formRendererRef.value.getFormData()

// 设置表单数据
formRendererRef.value.setFormData(formData.value)
```

## 事件执行器使用说明（Event Executor）

### 上下文参数

| 参数名         | 说明                          |
|----------------|-------------------------------|
| `widgetConfig` | 当前组件的配置内容             |
| `formData`     | 当前整个表单的填写数据         |
| `widgetList`   | 当前表单组件树                 |
| `value`        | 当前组件的值（仅在 onChange 中可用） |

---

### 可用方法

#### 1. `setHidden(hidden: boolean)`
设置当前组件的隐藏状态。

#### 2. `getValue(): any`
获取当前组件的值。

#### 3. `setValue(value: any)`
设置当前组件的值。

#### 4. `getFieldValue(fieldId: string): any`
通过id获取指定组件的填写内容

#### 5. `setFieldValue(fieldId: string, value: any)`
通过id设置指定组件的内容

#### 6. `setFieldHidden(fieldId: string, hidden: boolean)`
通过id设置指定组件显示状态

#### 7. `notify(message: string, type?: 'success' | 'info' | 'warning' | 'error', duration?: number)`
弹出提示消息。：
```js
notify('保存成功', 'success')
```

#### 8. `request`
发起网络请求，会携带传入的请求头信息
```js

// GET 请求
request.get('/api/user', { id: 1 }).then(res => {
  console.log(res)
})

// POST 请求
request.post('/api/user', { name: '' })

// PUT 请求
request.put('/api/user/1', { name: '' })

// DELETE 请求
request.delete('/api/user/1')
```

## 自定义组件配置说明

自定义组件的实现原理：通过一套统一的数据结构（customWidgetList）定义组件的类型（:is="config.type"）、属性（v-bind="config.attributes"）、事件（如 @change="handleChange"）、校验规则（rules），并结合 WidgetContainer 和 FormItemWidget 两个包装组件实现拖拽控制、表单校验等通用功能，最终通过动态组件机制在运行时渲染成真正的 Vue 组件，使设计器和渲染器都可以以 JSON 驱动的方式复用这些组件。

### 举个例子

```js
const customWidgetList = ref([{
  type: 'el-color-picker',//组件的名称，需要全局注册（必须）
  label: '颜色选择',//左侧列表对应组件名称（必须）
  id: 'color',//生成id时的前缀（必须）
  isCustomWidget: true,//是否是自定义组件（必须且固定为true）
  isFormItem: true,//是否属于表单组件（必须）
  attributes: {//此处填写的属性会使用v-bind绑定到对应组件上
    hidden: false, //是否隐藏
    label: '颜色选择',//标签名称 (表单组件必须)
    labelWidth: '',//标签宽度 (表单组件必须)
    showLabel: true,// 显示标签 (表单组件必须)
    disabled: false,//是否禁用
    size: 'default',//组件尺寸
    showAlpha: true,//自定义组件的单独属性，需要在attributesConfig下单独配置属性编辑器
  },
  attributesConfig: {//属性的描述，部分属性已内置无需定义
    showAlpha: {
      label: '支持透明度选择',
      component: {//属性所使用的编辑器控件,需全局注册
        name: 'el-switch',//使用el-switch作为属性配置器
        bind: {// 对应配置器的v-bind属性
          activeText: '是',
          inactiveText: '否',
          inlinePrompt: true,
          activeValue: true,
          inactiveValue: false
        }
      }
    }
  },
  rules: [],//验证规则，如果是表单组件则必须且固定为[]
  events: {
    onChange: '',//内容改变
    onMounted: ''//组件创建
  }
},])
```