介绍

Ele Plus Form是一个基于Element Plus UI库的扩展，用于简化Vue.js应用程序中的表单开发。它提供了一组自定义的表单组件和一些实用的功能，可以帮助您更轻松地构建和管理表单。 Ele Plus Form的特点和功能包括：

1. 自定义表单组件：Ele Plus Form提供了一系列的自定义表单组件，如Input、Select、DatePicker、Upload等，这些组件扩展了Element Plus原有的表单组件，增加了一些便捷的功能和选项。
2. 表单验证：Ele Plus Form内置了表单验证的功能，可以通过简单的配置进行表单字段的校验，包括必填字段、数据类型、最小/最大长度、正则表达式等。
3. 表单布局：Ele Plus Form提供了多种表单布局选项，可以根据需要选择水平布局或垂直布局，以及自定义字段的排列方式和样式。
4. 表单数据处理：Ele Plus Form提供了方便的表单数据处理方法，可以对表单数据进行格式化、转换和校验，使得数据的处理更加简单和灵活。
5. 表单事件处理：Ele Plus Form允许您监听表单的各种事件，如提交表单、重置表单等，以及自定义事件的处理逻辑。

代码预览

<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 | 手机号、身份证号、邮箱、链接、正数、整数、正整数、金额、中文 | - | 手机号、/^-?\d+$/ |

组合式 API

useDefaultValue(formData: object, defaultForm?: object)

调用 useDefaultValue 方法，接受两个参数： 参数一：当前表单formData(必传)； 参数二：默认的modelValue参数（选传）； 返回值：根据formData通过Vue3的reactive方法自动生成表单项的默认值。

<script setup>
  import { useDefaultValue } from 'ele-plus-form'
	const formData = ...
  
  const form = useDefaultValue(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 | 选填 | - | 根据lable自动生成 | 请输入姓名 | | 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.73+)

Attributes

| 参数 | 说明 | 类型 | 是否必填 | 可选值 | 默认值 | 举例 | | --- | --- | --- | --- | --- | --- | --- | | type | 表单项类型 | string | 必填 | table | - | - | | option | 带选项类表单项的数据项 | array/function | 必填 | - | - | 详见上方 | | fields | 表格数据字段 | object | 必填 | - | - | { name: '姓名', sex: '年龄' } | | 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 |

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内容'
  }
}