Form Dynamic Design

项目介绍

Form Dynamic 是一个基于 Vue 3 开发的动态表单设计器组件，提供直观的拖拽式界面来快速构建复杂表单。该组件支持丰富的表单项类型、动态联动、数据验证、权限控制等高级功能，适用于企业级应用中的表单配置场景。

功能特性

• 拖拽式设计：直观的拖拽界面，轻松构建复杂表单结构
• 丰富的表单项：支持输入框、选择器、日期选择器、文件上传等多种表单项类型
• 动态联动：支持表单项之间的数据联动和条件显示
• 数据验证：内置多种验证规则，支持自定义验证逻辑
• 权限控制：细粒度的字段权限管理
• 响应式设计：适配不同屏幕尺寸
• 模拟API支持：内置模拟数据接口，便于开发测试

技术栈

• Vue 3
• Element Plus
• Vue Draggable Plus
• Vite
• Sass

项目结构

src/
├── api/             # API相关模块，包含模拟数据和接口配置
├── common/          # 通用配置和工具
├── components/      # 表单组件库
├── composables/     # 可复用的组合式函数
├── const/           # 常量定义
├── dialogs/         # 对话框组件
├── store/           # 状态管理
├── utils/           # 工具函数
├── index.vue        # 主组件
└── plugin.js        # Vue插件配置

安装

NPM 安装

npm install form-dynamic

Yarn 安装

yarn add form-dynamic

使用方法

全局引入

在你的 Vue 应用入口文件中（如 main.js 或 main.ts）：

import { createApp } from 'vue'
import App from './App.vue'
import FormDynamic from 'form-dynamic'
import 'form-dynamic/dist/style.css'

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

按需引入

在需要使用的组件中：

import { FormDynamicDesigner } from 'form-dynamic'
import 'form-dynamic/dist/style.css'

export default {
  components: {
    FormDynamicDesigner
  }
}

基本使用

<template>
  <div>
    <form-dynamic-designer
      ref="formDesigner"
      :config="formConfig"
      @save="handleSave"
      @preview="handlePreview"
    />
  </div>
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const formConfig = ref({
      // 表单配置项
      title: '示例表单',
      fields: []
    })

    const handleSave = (config) => {
      console.log('保存表单配置:', config)
      // 保存到后端或本地存储
    }

    const handlePreview = (config) => {
      console.log('预览表单配置:', config)
      // 预览表单
    }

    return {
      formConfig,
      handleSave,
      handlePreview
    }
  }
}
</script>

模拟API模块使用说明

模拟API模块结构

该项目提供了内置的模拟API模块，用于开发和测试环境，结构如下：

• api/config.js: API配置管理
• api/index.js: API统一导出
• api/menu.js: 菜单相关模拟数据
• api/organization/: 组织相关模拟数据
• api/role.js: 角色相关模拟数据
• api/system/: 系统相关模拟数据
• api/user.js: 用户相关模拟数据

在组件中使用模拟API

import { getType, getBasicAll } from 'form-dynamic/api'

// 使用模拟API获取表单类型
getType().then(res => {
  console.log('表单类型数据:', res.data)
})

// 使用模拟API获取基础数据
getBasicAll().then(res => {
  console.log('基础数据:', res.data)
})

使用真实API

当前版本默认使用真实API，无需额外配置。表单设计器会自动调用配置的API接口获取数据。

你可以通过以下方式配置API参数：

// 通过插件配置自定义API参数
app.use(FormDynamic, {
  apiConfig: {
    // API基础URL
    baseURL: 'https://your-api-server.com/api',
    // 请求超时时间（毫秒）
    timeout: 30000,
    // 是否启用模拟数据模式（设置为true时使用模拟数据）
    mock: false
  }
})

// 或者在运行时更新API配置
import { updateApiConfig } from 'form-dynamic/api/config'
updateApiConfig({
  baseURL: 'https://api.example.com',
  timeout: 15000
})

使用模拟数据

当你需要在开发环境使用模拟数据时，可以通过以下方式配置：

import { createApp } from 'vue'
import App from './App.vue'
import FormDynamic from 'form-dynamic'
import 'form-dynamic/dist/style.css'

const app = createApp(App)

// 通过插件配置启用模拟数据模式
app.use(FormDynamic, {
  apiConfig: {
    // 启用模拟数据模式
    mock: true,
    // mockData 对象中定义各个API的模拟返回数据
    mockData: {
      // 角色列表模拟数据
      listRole: (params) => ({
        data: [
          { roleId: '1', roleName: '管理员', roleCode: 'ADMIN' },
          { roleId: '2', roleName: '普通用户', roleCode: 'USER' }
        ]
      }),
      // 用户列表模拟数据
      getUserList: (params) => ({
        code: 200,
        message: 'success',
        data: [
          { id: '1', username: 'admin', realName: '管理员' },
          { id: '2', username: 'user1', realName: '用户1' }
        ]
      }),
      // 菜单列表模拟数据
      getMenuList: () => ({
        data: [
          { menuId: '1', menuName: '首页', menuCode: 'HOME' },
          { menuId: '2', menuName: '设置', menuCode: 'SETTINGS' }
        ]
      }),
      // 资源类型模拟数据
      getType: () => ({
        data: [
          { typeId: '1', typeName: '表单', typeCode: 'FORM' },
          { typeId: '2', typeName: '报表', typeCode: 'REPORT' }
        ]
      }),
      // 基础数据模拟数据
      getBasicAll: (dictType) => ({
        data: {}
      }),
      // 动态字段模拟数据
      getRelateFormFields: (formId) => ({
        data: []
      }),
      // 保存表单配置模拟数据
      putSysForm: (data) => ({
        code: 200,
        message: '保存成功'
      }),
      // 获取表单配置模拟数据
      getFormConfig: (formId) => ({
        data: {
          basic: {
            code: 'demo_form',
            name: '示例表单'
          },
          areaComponents: {}
        }
      })
    }
  }
})

app.mount('#app')

直接使用API配置工具

除了通过插件配置外，你还可以在应用运行时直接更新API配置：

import { updateApiConfig } from 'form-dynamic/api'

// 更新API配置
updateApiConfig({
  mockData: {
    listRole: {
      data: [
        // 你的自定义角色数据
      ]
    },
    // 其他API的模拟数据...
  }
})

// 获取当前API配置
import { getApiConfig } from 'form-dynamic/api'
const currentConfig = getApiConfig()
console.log('当前API配置:', currentConfig)

API配置优先级

表单设计器在处理API调用时的优先级机制如下：

1. 首先检查是否启用模拟模式：

   • 如果 mock: true，则使用模拟数据
   • 如果 mock: false（默认），则直接调用真实API

2. 在模拟模式下的优先级：

   • 优先使用你通过 apiConfig.mockData 提供的自定义模拟数据函数
   • 如果没有提供对应的模拟数据函数，则使用内置的默认模拟数据

3. API参数配置：

   • baseURL: API基础URL（默认: '/api'）
   • timeout: 请求超时时间（默认: 30000毫秒）
   • mock: 是否启用模拟数据模式（默认: false）
   • mockData: 自定义模拟数据函数对象

这种优先级机制确保你可以在开发和测试环境中灵活切换真实API和模拟数据，同时保持配置的简洁性和可维护性。

API参考

FormDynamicDesigner 组件 Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | Object | {} | 表单配置对象 | | disabled | Boolean | false | 是否禁用设计器 | | showHeader | Boolean | true | 是否显示头部工具栏 | | showFooter | Boolean | true | 是否显示底部操作栏 | | locale | String | 'zh-CN' | 语言设置 | | theme | Object | {} | 主题配置 |

FormDynamicDesigner 组件 Events

| 事件 | 参数 | 说明 | |------|------|------| | save | config: Object | 保存表单配置时触发 | | preview | config: Object | 预览表单时触发 | | reset | - | 重置表单设计器时触发 | | change | config: Object | 表单配置变更时触发 | | error | error: Object | 发生错误时触发 |

工具函数

配置合并

import { mergeConfig } from 'form-dynamic/utils/configMerger'

const defaultConfig = { /* 默认配置 */ }
const customConfig = { /* 自定义配置 */ }
const mergedConfig = mergeConfig(defaultConfig, customConfig)

配置序列化/反序列化

import { serializeConfig, deserializeConfig } from 'form-dynamic/utils/configHandler'

// 序列化配置为字符串
const configStr = serializeConfig(formConfig)

// 从字符串反序列化配置
const configObj = deserializeConfig(configStr)

高级示例

自定义组件

<template>
  <form-dynamic-designer
    :config="formConfig"
    :custom-components="customComponents"
    @save="handleSave"
  />
</template>

<script>
import { ref } from 'vue'
import MyCustomComponent from './components/MyCustomComponent.vue'

export default {
  setup() {
    const formConfig = ref({})
    
    const customComponents = [
      {
        type: 'my-custom',
        name: '自定义组件',
        component: MyCustomComponent,
        props: {
          label: '自定义组件',
          placeholder: '请输入'
        }
      }
    ]
    
    const handleSave = (config) => {
      console.log('保存配置:', config)
    }
    
    return {
      formConfig,
      customComponents,
      handleSave
    }
  }
}
</script>

数据联动示例

<template>
  <form-dynamic-designer
    :config="formConfig"
    @change="handleConfigChange"
  />
</template>

<script>
import { ref } from 'vue'

export default {
  setup() {
    const formConfig = ref({
      title: '数据联动示例',
      fields: [
        {
          type: 'select',
          field: 'department',
          label: '部门',
          options: [
            { label: '技术部', value: 'tech' },
            { label: '市场部', value: 'marketing' }
          ],
          required: true
        },
        {
          type: 'select',
          field: 'employee',
          label: '员工',
          options: [],
          required: true,
          // 数据联动配置
          dependencies: ['department'],
          // 根据部门动态获取员工选项
          optionsProvider: (values) => {
            const { department } = values
            // 这里可以调用API获取数据
            if (department === 'tech') {
              return [
                { label: '张三', value: 'zhangsan' },
                { label: '李四', value: 'lisi' }
              ]
            } else if (department === 'marketing') {
              return [
                { label: '王五', value: 'wangwu' },
                { label: '赵六', value: 'zhaoliu' }
              ]
            }
            return []
          }
        }
      ]
    })
    
    const handleConfigChange = (config) => {
      console.log('配置已变更:', config)
    }
    
    return {
      formConfig,
      handleConfigChange
    }
  }
}
</script>

浏览器兼容性

• Chrome (最新2个版本)
• Firefox (最新2个版本)
• Safari (最新2个版本)
• Edge (最新2个版本)

License

MIT

开发与贡献

欢迎贡献代码和问题反馈！请在提交PR前确保通过所有测试。

开发环境设置

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview