EleForm 基础表单组件

组件介绍

EleForm 是一个基于 Element UI 封装的动态表单生成器，用于快速构建复杂的表单页面。它支持多种表单控件类型，包括输入框、选择器、上传组件等，并提供了丰富的配置选项。

安装与引入

安装依赖

# 安装基础组件
npm install diandi-ele-form

# 安装相关扩展组件
npm install diandi-ele-form-image-uploader diandi-ele-form-upload-file diandi-ele-form-video-uploader
npm install diandi-ele-form-tree-select diandi-ele-form-dynamic diandi-ele-form-bmap diandi-ele-form-tmap
npm install diandi-ele-form-filter diandi-ueditor

全局引入

在 src/projects/scrm/utils/el-form.js 中全局引入和配置：

import Vue from 'vue'
import store from '@projectName/store'

// 引入 diandi-ele-form
import EleForm from 'diandi-ele-form/lib'

// 配置上传相关参数
const config = {
  fileSize: store.getters.elForm.fileSize,
  chunkSize: store.getters.elForm.chunkSize, // 分片尺寸（M）
  action: store.getters.elForm.action, // 图片上传地址
  uploadFile: store.getters.elForm.uploadFile, // 文件上传地址
  uploadMerge: store.getters.elForm.uploadMerge, // 分配合并地址
  attachmentUrl: store.getters.elForm.attachmentUrl,
  ueditorServerUrl: store.getters.elForm.ueditorServerUrl,
  headers: store.getters.elForm.headers
}

// 全局配置
Vue.use(EleForm, {
  // 所有和上传相关(上传图片, 上传视频, 富文本中图片上传)
  upload: config,
  // 其他全局配置...
})

全局配置

上传配置

// 所有和上传相关的配置
upload: {
  fileSize: Number, // 文件大小限制
  chunkSize: Number, // 分片尺寸（M）
  action: String, // 图片上传地址
  uploadFile: String, // 文件上传地址
  uploadMerge: String, // 分配合并地址
  attachmentUrl: String, // 附件访问地址
  ueditorServerUrl: String, // 百度编辑器服务地址
  headers: Object // 请求头
}

数字类型配置

// number类型
number: {
  min: 0 // 所有 number 类型, 最小值为 0
}

基本使用

简单表单

<template>
  <ele-form
    :form-data="formData"
    :form-config="formConfig"
    @submit="handleSubmit"
  />
</template>

<script>
export default {
  data() {
    return {
      formData: {
        name: '',
        age: 0
      },
      formConfig: [
        {
          label: '姓名',
          prop: 'name',
          type: 'input'
        },
        {
          label: '年龄',
          prop: 'age',
          type: 'number'
        }
      ]
    }
  },
  methods: {
    handleSubmit(data) {
      console.log('表单数据:', data)
    }
  }
}
</script>

复杂表单

<template>
  <ele-form
    :form-data="formData"
    :form-config="formConfig"
    :inline="false"
    :label-width="'120px'"
    @submit="handleSubmit"
  />
</template>

<script>
export default {
  data() {
    return {
      formData: {
        name: '',
        avatar: '',
        files: [],
        videos: [],
        category: '',
        dynamicFields: [],
        location: ''
      },
      formConfig: [
        {
          label: '姓名',
          prop: 'name',
          type: 'input',
          required: true
        },
        {
          label: '头像',
          prop: 'avatar',
          type: 'image-uploader',
          props: {
            limit: 1
          }
        },
        {
          label: '文件',
          prop: 'files',
          type: 'upload-file'
        },
        {
          label: '视频',
          prop: 'videos',
          type: 'video-uploader'
        },
        {
          label: '分类',
          prop: 'category',
          type: 'tree-select',
          props: {
            data: [] // 树形数据
          }
        },
        {
          label: '动态字段',
          prop: 'dynamicFields',
          type: 'dynamic',
          formConfig: [
            {
              label: '名称',
              prop: 'name',
              type: 'input'
            },
            {
              label: '值',
              prop: 'value',
              type: 'input'
            }
          ]
        },
        {
          label: '位置',
          prop: 'location',
          type: 'bmap'
        }
      ]
    }
  },
  methods: {
    handleSubmit(data) {
      console.log('表单数据:', data)
    }
  }
}
</script>

常用属性

属性类型描述默认值
form-dataObject表单数据对象{}
form-configArray表单配置数组[]
inlineBoolean是否行内表单false
label-widthString标签宽度'80px'
sizeString表单大小'medium'
disabledBoolean是否禁用false
readonlyBoolean是否只读false
show-submitBoolean是否显示提交按钮true
show-resetBoolean是否显示重置按钮true
submit-textString提交按钮文本'提交'
reset-textString重置按钮文本'重置'

事件

事件名称回调参数描述
submitformData表单提交时触发
reset-表单重置时触发
validateresult, formData表单验证时触发

表单配置项

基础配置

{
  label: String, // 标签文本
  prop: String, // 字段名
  type: String, // 表单类型
  required: Boolean, // 是否必填
  disabled: Boolean, // 是否禁用
  readonly: Boolean, // 是否只读
  placeholder: String, // 占位符
  defaultValue: Any, // 默认值
  rules: Array, // 验证规则
  props: Object, // 组件属性
  attrs: Object, // 元素属性
  class: String, // 自定义类名
  style: Object, // 自定义样式
  col: Number, // 栅格列数
  offset: Number, // 栅格偏移
  suffix: String, // 后缀文本
  prefix: String, // 前缀文本
  hidden: Boolean, // 是否隐藏
  component: Object, // 自定义组件
  render: Function, // 自定义渲染函数
  onChange: Function, // 值变化回调
  onBlur: Function, // 失焦回调
  onFocus: Function, // 聚焦回调
  options: Array, // 选项数据
  remote: Boolean, // 是否远程搜索
  remoteMethod: Function, // 远程搜索方法
  filterable: Boolean, // 是否可筛选
  multiple: Boolean, // 是否多选
  clearable: Boolean, // 是否可清空
  collapseTags: Boolean, // 是否折叠标签
  showPassword: Boolean, // 是否显示密码
  rows: Number, // 文本域行数
  min: Number, // 最小值
  max: Number, // 最大值
  step: Number, // 步长
  precision: Number, // 精度
  format: String, // 格式化
  valueFormat: String, // 值格式化
  rangeSeparator: String, // 范围分隔符
  startPlaceholder: String, // 开始占位符
  endPlaceholder: String, // 结束占位符
  pickerOptions: Object, // 选择器选项
  uploadOptions: Object, // 上传选项
  action: String, // 上传地址
  responseFn: Function, // 响应处理函数
  limit: Number, // 上传数量限制
  fileSize: Number, // 文件大小限制
  accept: String, // 接受的文件类型
  data: Object, // 上传额外数据
  headers: Object, // 上传请求头
  withCredentials: Boolean, // 是否携带凭证
  autoUpload: Boolean, // 是否自动上传
  listType: String, // 文件列表类型
  drag: Boolean, // 是否支持拖拽
  data: Array, // 树形数据
  nodeKey: String, // 节点键名
  props: Object, // 树形配置
  checkStrictly: Boolean, // 是否严格勾选
  defaultExpandAll: Boolean, // 是否默认展开所有
  expandOnClickNode: Boolean, // 是否点击节点展开
  checkOnClickNode: Boolean, // 是否点击节点勾选
  renderContent: Function, // 自定义节点渲染
  formConfig: Array, // 动态表单配置
  template: Object, // 动态表单模板
  addBtnText: String, // 添加按钮文本
  delBtnText: String, // 删除按钮文本
  max: Number, // 最大数量
  min: Number, // 最小数量
  title: String, // 弹窗标题
  width: String, // 弹窗宽度
  height: String, // 弹窗高度
  ak: String, // 地图AK
  center: Array, // 地图中心点
  zoom: Number, // 地图缩放级别
  marker: Boolean, // 是否显示标记
  search: Boolean, // 是否显示搜索
  resizeEnable: Boolean, // 是否允许调整大小
  enableMapClick: Boolean, // 是否允许地图点击
  plugin: Array, // 地图插件
  serverUrl: String, // 编辑器服务地址
  initialFrameWidth: String, // 初始宽度
  initialFrameHeight: Number, // 初始高度
  toolbars: Array, // 工具栏配置
  zIndex: Number, // 层级
  name: String, // 图标名称
  size: String, // 图标大小
  color: String // 图标颜色
}

常见问题

1. 上传失败

原因：上传地址配置错误或网络问题

解决方案：

  • 检查 store.getters.elForm.action 等上传地址配置
  • 确认服务器端是否正常接收上传请求
  • 检查网络连接和跨域配置

2. 表单验证不生效

原因：验证规则配置错误或组件类型不匹配

解决方案：

  • 检查 rules 配置是否正确
  • 确认 prop 字段名与 formData 中的字段一致
  • 对于自定义组件，确保正确实现了验证逻辑

3. 动态表单数据不更新

原因：数据绑定或配置更新问题

解决方案：

  • 确保 formData 中的字段与表单配置对应
  • 使用 this.$set 或 Vue.set 更新嵌套对象
  • 检查动态表单的 formConfig 是否正确配置

示例代码

完整表单示例

<template>
  <div class="form-container">
    <h2>用户信息表单</h2>
    <ele-form
      :form-data="formData"
      :form-config="formConfig"
      :label-width="'120px'"
      @submit="handleSubmit"
      @reset="handleReset"
    />
  </div>
</template>

<script>
export default {
  name: 'UserForm',
  data() {
    return {
      formData: {
        name: '',
        email: '',
        avatar: '',
        files: [],
        category: '',
        tags: [],
        dynamicFields: []
      },
      formConfig: [
        {
          label: '姓名',
          prop: 'name',
          type: 'input',
          required: true,
          placeholder: '请输入姓名'
        },
        {
          label: '邮箱',
          prop: 'email',
          type: 'input',
          required: true,
          placeholder: '请输入邮箱',
          rules: [
            {
              type: 'email',
              message: '请输入正确的邮箱地址',
              trigger: 'blur'
            }
          ]
        },
        {
          label: '头像',
          prop: 'avatar',
          type: 'image-uploader',
          props: {
            limit: 1,
            accept: 'image/*'
          }
        },
        {
          label: '附件',
          prop: 'files',
          type: 'upload-file'
        },
        {
          label: '分类',
          prop: 'category',
          type: 'tree-select',
          props: {
            data: [
              {
                label: '分类1',
                value: '1',
                children: [
                  {
                    label: '子分类1-1',
                    value: '1-1'
                  }
                ]
              },
              {
                label: '分类2',
                value: '2'
              }
            ]
          }
        },
        {
          label: '标签',
          prop: 'tags',
          type: 'select',
          multiple: true,
          options: [
            { label: '标签1', value: '1' },
            { label: '标签2', value: '2' },
            { label: '标签3', value: '3' }
          ]
        },
        {
          label: '动态字段',
          prop: 'dynamicFields',
          type: 'dynamic',
          formConfig: [
            {
              label: '字段名',
              prop: 'name',
              type: 'input'
            },
            {
              label: '字段值',
              prop: 'value',
              type: 'input'
            }
          ]
        }
      ]
    }
  },
  methods: {
    handleSubmit(data) {
      console.log('表单提交:', data)
      // 这里可以进行API调用等操作
      this.$message.success('提交成功')
    },
    handleReset() {
      console.log('表单重置')
      this.$message.info('表单已重置')
    }
  }
}
</script>

<style scoped>
.form-container {
  max-width: 800px;
  margin: 0 auto;
  padding: 20px;
  background: #f9f9f9;
  border-radius: 8px;
  box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.1);
}

h2 {
  margin-bottom: 20px;
  color: #303133;
}
</style>

总结

EleForm 是一个功能强大的动态表单生成器，通过简单的配置即可快速构建复杂的表单页面。它支持多种表单控件类型，提供了丰富的配置选项，并且可以与 Element UI 无缝集成。

通过全局配置和组件级配置的结合，可以灵活应对各种表单场景，大大提高了开发效率。

版本信息