动态表单【ele-plus-form】组件需求反馈开放中（ By Vue3 + Element Plus）

更新日志

目前公司项目已完整投入使用，现开源吸收大家的需求反馈，待功能需求整理并开发完毕后，大家可以试着使用。

代码预览

<template>
  <ele-form ref="eleFormRef" v-model="form" :form-data="formData" />
  <el-button type="primary" @click='submit'>提交</el-button>
</template>

<script setup>
  import { reactive } from 'vue'
  import { defineValue } from 'ele-plus-form'
  
  // 表单配置项
  const formData = reactive({
    studentName: {
      type: 'input', label: '学生姓名', span: 12
    },
    studentNo: {
      type: 'input', label: '身份证号', span: 12
    },
    sex: {
      type: 'radio', label: '性别', option: { 1: '男', 2: '女' }
      // 将 radio 改成 select 即可将单选框变成下拉框
      // type: 'select'
    }
  })
  
  // form表单数据
  const form = defineValue(formData)

  const eleFormRef = ref()
  const submit = () => {
    eleFormRef.value.validate(() => {
      // 校验成功，提交表单
    })
  }
</script>

一、ElePlusForm

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
formData	表单数据项	object	必填	-	-	见下方
v-model/modelValue	表单绑定值	object	必填	-	-	-
span	布局分栏数(同Element UI)	number	选填	1-24	24	8
disabled	form全部禁用	boolean	选填	false/true	false	true
required	是否必填	boolean	选填	false/true	true	false
divider	分割线内容	string	选填	-	-	基础信息
ref	Vue组件的ref属性	string	-	-	-	-
message(0.3.3+)	自定义校验必填时的错误提示	string	选填	-	-	姓名不能为空
minHeight(0.4.4+)	elePlusForm最小高度	string	选填	-	200px	auto
maxHeight(0.4.4+)	elePlusForm最大高度	string	选填	-	-	800px

Events

事件名	说明	举例
validate	提交验证	formRef.validate(() => { // todo })
validateField	验证具体的某个字段	formRef.validateField(() => { // todo })
resetFields	重置表单	formRef.resetFields()
clearValidate	清理某个字段的表单验证信息	formRef.clearValidate()

表单验证相关

参数	说明	类型	可选值	默认值	举例
required	表单项是否为必填	boolean	true/false	true	false
validator	自定义验证规则	array/function	-	-	同element UI，示例见完整示例
rule(0.3.3+)	type为输入框类型时，使用ele-form自带的校验规则或正则规则	string/RegExp	手机号、身份证号、邮箱、链接、正数、整数、正整数、金额、中文、IP地址(0.5.0+)	-	手机号、/^-?\d+$/

组合式 API

defineValue(formData: object, defaultForm?: object)

调用 defineValue 方法，接受两个参数：

参数一：当前表单formData(必传)；

参数二：默认的modelValue参数（选传）；

返回值：根据formData通过Vue3的reactive方法自动生成表单项的默认值。

<script setup>
  import { defineValue } from 'ele-plus-form'
	const formData = ...
  
  const form = defineValue(formData, {
    sex: 1,
    name: '张三'
  })
</script>

二、FormData Attributes

采用键值对形式，其中key为表单项字段，value则为该表单配置项，以下简称attrs

attrs 通用参数

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	见下方	-	-
label	标签文本	string	必填	-	-	-
required	是否必填	boolean/function/number	选填	false/true	true
disabled	禁用	any/function/boolean	选填	false/true	false	0/true/(form) => state.disabled
show	控制表单项显隐方法，接受function返回值为布尔类型	function	选填	-	-	(form) => form.type == 1
prompt	label后面的提示信息	object/string	选填	-	title默认为“提示”，width默认为200	{title: '提示', content: '提示内容', width: 200} 、'提示内容'

attrs.type 类型

类型	名称
输入框类	输入框input、数字框number、整数框integer、文本框textarea
带选项类	下拉框select、单选框radio、radioButton、多选框checkbox、穿梭框transfer (0.3.9+)
开关类	开关switch
日期选择器类	年year、月month、年月日date、年月日时分秒datetime、年月日时分秒范围选择datetimerange、年月日范围选择daterange
时间选择器类	时间time、时间范围timerange
上传文件	upload
动态表单	dynamicForm
简单表格	table
富文本	editor
自定义插槽	slot
html	html

三、输入框类

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	input/number/integer/textarea/password/code (0.2.9+)	-	input
placeholder	占位符	string/function(0.5.0+)	选填	-	根据lable自动生成	请输入姓名/(form) => {}
prepend	type为input/number/integer类型是输入框前置内容	string	选填	-	-	¥
append	type为input/number/integer类型是输入框后置内容	string	选填	-	-	元
maxlength	输入框类型表单项最大内容长度	number	选填	-	无限制	200
rows	type为textarea时的行数	number	选填	-	4	6
min	type为textarea时的行数最小值	number	选填	-	-	-
rule	使用ElePlusForm内置校验规则	string	选填	phone、idNumber、email、link	-	phone
time (0.2.9+)	type为code时，验证码重新发送的时间	number	选填	-	60	30
button (0.4.0+)	后置按钮	object	选填	-	-	-

button属性 (0.4.0+)

参数	说明	举例
name	按钮文本	提交
onClick	点击事件	(value, form) => {}
其他属性同Element Plus ElButton属性	-	-

Function (0.3.55+新增第二个参数form)

参数	说明	举例
onInput	输入事件	(value, form) => {}
onBlur	失焦事件	(value, form) => {}
onChange	change事件	(value, form) => {}
onSendCode (0.2.9+)	发送验证码异步方法，type为code时必传	(value) => Promise，value：value为输入框的值，调用后需返回 Promise

基础示例

const formData = {
  name: {
    type: 'input',
    label: '姓名',
    rule: '中文',
    onChange: (e) => {
      console.log(e)
    }
  }
}

四、带选项类

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	select/radio/radioButton/checkbox/transfer(0.3.9+)	-	-
option	带选项类表单项的数据项	array/object/function	必填	-	-	详见下方
placeholder	type为select时占位符	string	选填	-	type为select时根据lable自动生成	根据lable自动生成
labelKey	option为数组时，label的对应key	string	选填	-	label	name
valueKey	option为数组时，value的对应key	string	选填	-	value	id
extraKey(0.4.80+)	下拉框中额外展示的数据字段	string	选填	-	-	name
virtual(0.4.80+)	下拉框是否开启虚拟列表，开启后，el-select将改为el-select-v2	boolean	选填	-	false	true

option

类型	举例
对象	option: { 1: '张三', 2: '李四' }
标准数组	option: [{label: '张三', value: 1}, {label: '李四', value: 2}]
非标准数组	option: [{name: '张三', id: 1}, {name: '李四', id: 2}]``labelKey:'name'``valueKey: 'id'
Function	option: (form) => state.option

Function

参数	说明	举例
onChange	change事件	(value/values, item/items, form) => {}，value/values：当前选中的 value；item (0.3.0+)：单选时为当前 value 对应的 item；多选时为(multiple、checkbox、transfer)当前选中的多个 value 对应的 items

基础示例

// 数组或动态数组形式选项
const state = reactive({
  option: [
    { label: '足球', value: 1 },
    { label: '篮球', value: 3 }
  ]
})

const formData = {
  value1: {
    type: 'radio',
    label: '性别',
    option: { 1: '男', 2: '女' }, // 对象形式选项
    onChange: (e, item) => {
      console.log(e, item)
    }
  },
  value2: {
    type: 'radioButton',
    label: '性别',
    option: { 1: '男', 2: '女' }, // 对象形式选项
    onChange: (e, item) => {
      console.log(e, item)
    }
  },
  value4: {
    type: 'select',
    label: '爱好',
    option: () => state.option, // 数组或动态数组形式选项
    onChange: (e, item) => {
      console.log(e, item)
    }
  },
  value5: {
    type: 'transfer',
    label: '爱好',
    option: () => state.option, // 数组或动态数组形式选项
    onChange: (e, item) => {
      console.log(e, item)
    }
  },
  value6: {
    type: 'select',
    label: '爱好',
    option: () => state.option, // 数组或动态数组形式选项
    virtual: true, // 开启虚拟列表
    extraKey: 'className', // 额外展示的字段
    onChange: (e, item) => {
      console.log(e, item)
    }
  }
}

五、开关类

Attributes

参数	说明	类型	是否必填	可选值	默认值
type	表单项类型	string	必填	switch	-
activeValue	switch 打开时的值	boolean/string/number	选填	-	true
inactiveValue	switch 关闭时的值	boolean/string/number	选填	-	false

Function

参数	说明	举例
onChange	change事件	() => {}

基础示例

const formData = {
  isOpen: {
    type: 'switch',
    label: '是否启用',
    activeValue: 1,
    inactiveValue: 0,
    onChange: () => {}
  }
}

六、日期选择器类

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	year/month/date/datetime/datetimerange/daterange	-	-
placeholder	输入框类型表单项占位符	string/function	选填	-	根据lable自动生成	请选择日期
format	日期格式	string	选填	-	yyyy-MM-dd HH:mm:ss	-
pickerOptions	当前时间日期选择器特有的选项参考下表(同Element UI)	object/function	选填	-	-	-
prepend (0.3.4+)	选择框前置的内容	string	选填	-	-	2022年
append (0.3.4+)	选择框后置的内容	string	选填	-	-	:59

Function

参数	说明	举例
onChange	change事件	(value) => {}

基础示例

const formData = {
  date: {
    type: 'datetime',
    label: '活动开始时间',
    onChange: (e) => {
      console.log(e)
    }
  }
}

七、时间选择器类

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	time	-	-
placeholder	输入框类型表单项占位符	string/function	选填	-	-	请选择日期
format	日期格式	string	选填	-	HH:mm:ss	-
pickerOptions	当前时间日期选择器特有的选项参考下表(同Element UI)	object/function	选填	-	-	-
prepend (0.3.4+)	选择框前置的内容	string	选填	-	-	00:
append (0.3.4+)	选择框后置的内容	string	选填	-	-	:59

Function

参数	说明	举例
onChange	change事件	(value) => {}

基础示例

const formData = {
  date: {
    type: 'time',
    label: '放学时间',
    onChange: (e) => {
      console.log(e)
    }
  }
}

八、上传文件 (0.2.8+)

全局配置上传接口

在引入Ele Plus Form的时候，需传入uploadApi方法，uploadApi的返回值必须为Promise，即：uploadApi: (file, attrbuites) => Promise，

调用该Promise后，期望返回的数据为文件链接：

import ElePlusForm from 'ele-plus-form'
import 'ele-plus-form/dist/style.css'

app.use(ElePlusForm, {
  uploadMaxSize: xxx, // 最大文件大小，单位M
  uploadApi: (file, attrbuites) => {
    // 文件对象
    const fileData = new FormData()
    fileData.append('file', file)
    // 上传时附带的额外参数
    for (const key in attrbuites) {
      fileData.append(key, attrbuites[key])
    }
    
    // 上传接口
    uploadApi(fileData).then(({data}) => {
      // data 即为文件链接
    })
  }
})

Attributes

参数	说明	类型	是否必填	可选值	默认值
type	表单项类型	string	必填	upload	-
fileType	文件类型	string	选填	image/text	image
max	文件上传最多数量	number	选填	-	不限制
accept	文件格式限制	string	选填	同input[type=file]的accept属性	image/*
multiple	是否允许多选	boolean	选填	false/true	false
maxSize	文件最大大小，单位M	number	选填	-	不限制
width (0.3.92+)	图片上传框宽度	string	选填	-	100px
height (0.3.92+)	图片上传框高度	string	选填	-	100px
data（自定义参数）	上传时附带的额外参数	{ [key: string], any }	选填	-	-
headers（自定义参数）	设置上传的请求头部	{ [key: string], any }	选填	-	-
更多自定义参数	自定义参数，即方法uploadApi参数attrbuites需要的参数，可自行设置	any	选填	-	-

Function

参数	说明	举例
onChange	监听文件上传成功后、文件删除后	(fileList) => {}
onBeforeUpload	监听文件开始上传之前，返回false禁止上传，无返回值或者返回true，允许上传	(fileList) => boolean
onBeforeRemove	监听文件移除之前，返回false禁止移除，无返回值或者返回true，允许移除	(item, index) => boolean

基础示例

const formData = {
  date: {
    type: 'upload',
    label: '上传图片',
    onChange: (fileList) => {
      console.log(fileList)
    }
  }
}

九、动态表单

Attributes

参数	说明	类型	是否必填	可选值	默认值	示例
type	表单项类型	string	必填	dynamicForm	-	dynamicForm
defaultValue	每一项的默认值	object	必填	-	{}	{ name: '', list: [] }
formData	动态表单项集合（同五、FormData Attributes）	object	必填	-	-	-
max	动态表单项最大添加数量	number	选填	-	-	5
min	动态表单项最小添加数量	number	选填	-	-	2
dynamic	是否允许添加、移除	boolean	选填	false/true	true	false
disabled	禁用	boolean	选填	false/true	false	true
itemSpan	布局分栏	number	选填	0-24	24	12
className	类名	string	选填	-	-	form-item
option(0.4.5+)	选项模式的选项，多余的参数请组装好放进option里	array/object/function（同带选项类表单项的option）	选填	-	-	[ { label: '苹果', value: 'Apple', price: 2 } ]，change时多余的参数如price，会被添加进form里面
optionField(0.4.5+)	选项模式下选项对应的字段名	string	选填，声明了option属性后必填	-	-	-

Function

参数	说明	举例
onAdd	监听添加动态表单项时，非选项模式下：返回false禁止添加，无返回值或者返回true，允许添加	() => boolean，选项模式：(item) => {} (0.4.5+)
onRemove	监听移除动态表单项时，非选项模式下：返回false禁止移除，无返回值或者返回true，允许移除	(item) => boolean，选项模式：(item) => {} (0.4.5+)

基础示例

const formData = {
  list: {
    type: 'dynamicForm',
    label: '配置选项',
    min: 1,
    max: 4,
    itemSpan: 12,
    defaultValue: {
      label: '',
      value: ''
    },
    formData: {
      label: {
        type: 'input',
        label: '选项名称',
        span: 12
      },
      value: {
        type: 'input',
        label: '选项值',
        span: 12
      }
    }
  }
}

// 选项模式 option和optionField
const formData = {
  list: {
    type: 'dynamicForm',
    label: '配置选项',
    option: [
      { value: 1, label: '苹果', name: 'Apple' },
      { value: 2, label: '香蕉', name: 'Banan' },
      { value: 3, label: '火龙果', name: 'Huolong' }
    ],
    optionField: 'fruitKey',
    max: 2,
    itemSpan: 12,
    defaultValue: {
      label: '',
      value: ''
    },
    formData: {
      label: {
        type: 'input',
        label: '选项名称',
        span: 12
      },
      value: {
        type: 'input',
        label: '选项值',
        span: 12
      }
    }
  }
}

十、级联选择器(0.4.98+)

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	cascader	-	-
option	带选项类表单项的数据项	array/function	非懒加载模式必填	-	-	详见下方
multiple	多选	boolean	非必填	true/false	false	true
checkStrictly	是否严格的遵守父子节点不互相关联	boolean	非必填	true/false	false	true
emitPath	在选中节点改变时，是否返回由该节点所在的各级菜单的值所组成的数组，若设置 false，则只返回该节点的值	boolean	非必填	true/false	false	true
labelKey	label的对应key	string	非必填	-	label	name
valueKey	value的对应key	string	非必填	-	value	id
childrenKey	children的对应key	string	非必填	-	children	childList

option

类型	举例
数组	option: [{name: '张三', id: 1, children: [...]}, {name: '李四', id: 2}]
Function	option: (form) => state.option

Function

参数	说明	举例
onChange	change事件	(values, nodes, form) => {}
onLazyLoad	声明后该方法后，表示开启懒加载模式，option将失效	(node, resolve) => {}

基础示例

// 正常模式
const formData = {
  className: {
    type: 'cascader',
    label: '选择班级',
    option: [
      { name: '小学', id: '1', children: [{name: '小学一年级', id: '1-1'}] },
      { name: '初中', id: '2', children: [{name: '初中一年级', id: '2-1'}] },
      { name: '高中', id: '3', children: [{name: '高中一年级', id: '3-1'}] }
    ],
    labelKey: 'name',
    valueKey: 'id',
    onChange: (value, nodes, form) => {
      // value：值
      // nodes：选中的所有节点
      // form：当前表单
    }
  }
}

// 懒加载模式
let id = 0
const formData = {
  className: {
    type: 'cascader',
    label: '选择班级',
   	onLazyLoad: (node, resolve) => {
      const { level } = node
      setTimeout(() => {
        const nodes = Array.from({ length: level + 1 }).map((item) => ({
          value: ++id,
          label: `班级 - ${id}`,
          leaf: level >= 2
        }))
        resolve(nodes)
      }, 1000)
    }
  }
}

十一、简单表格(0.4.73+)

由于表单项select最多展示一种或两种信息，有时我们需要展示更多的信息，这时候我们就可以使用该表格，当然，具有复杂操作的表格请使用slot插槽自定义表格

Attributes

参数	说明	类型	是否必填	可选值	默认值	举例
type	表单项类型	string	必填	table	-	-
option	带选项类表单项的数据项	array/function	必填	-	-	详见下方
fields	表格数据字段	object	必填	-	-	{ name: '姓名', sex: '年龄', count: 对象格式见下方 }
maxHeight	表格最大高度	string	非必填	-	24vh	40vh
selectable	是否开启多选	boolean	非必填	true/false	false	true
max(0.4.9+)	开启多选后，最大的选中数量	number	非必填	-	不限制	5
rowKey(0.4.91+)	开启多选后，行唯一标识，默认为value (*注：开启多选后，option中必须包含该字段)	string	开启多选后，必填	-	value	id

fields

类型	举例
String	{ name: '姓名', age: '年龄' }
Object(0.5.0+)	支持输入框，格式同表单项输入框，见下方

fields: {
  age: {
    type: 'input',
    label: '年龄',
    append: '岁',
    rule: '正整数',
  }
}

option

类型	举例
Array	option: [{name: '张三', id: 1}, {name: '李四', id: 2}]
Function	option: (form) => state.option

Function

参数	说明	举例
onChange	change事件	(values, items, form) => {}

基础示例

const formData = {
  table: {
    type: 'table',
    label: '学生信息',
    option: [
      { name: '李四', value: '1', school: '成都一中', isFirst: true, rowspan: 2 },
      { name: '王五', value: '2', school: '成都一中', isFirst: false, rowspan: 2 },
      { name: '赵二', value: '3', school: '成都二中', isFirst: true, rowspan: 1 }
    ],
    max: 2,
    // 表格数据字段
    fields: {
      school: '学校',
      name: '姓名'
    },
    // 开启多选
    selectable: true,
    // 合并单元格
    spanMethod: ({ row, column }) => {
      if (column.label == '学校') {
        const { isFirst, rowspan } = row
        if (isFirst) {
          return { rowspan, colspan: 1 }
        } else {
          return { rowspan: 0, colspan: 0 }
        }
      }
    }
  }
}

十二、富文本

Attributes

参数	说明	类型	可选值	默认值
type	表单项类型	string	editor	-

Function

参数	说明	举例
onInput	输入事件（已添加防抖）	(value) => {}

基础示例

const formData = {
  content: {
    type: 'editor',
    label: '内容'
  }
}

十三、插槽slot

Attributes

参数	说明	类型	可选值	默认值
type	表单项类型	string	slot	-

基础示例

<ele-plus-form ref="eleFormRef" v-model="state.form" :form-data="formData">
  <template #list>
    列表内容
  </template>
</ele-plus-form>

const formData = {
  list: {
    type: 'slot',
    label: '列表'
  }
}

十四、html

Attributes

参数	说明	类型	可选值	默认值
type	表单项类型	string	html	-

基础示例

const formData = {
  content: {
    type: 'html',
    label: 'HTML内容'
  }
}