0.7.7 • Published 2 years ago

ele-plus-form v0.7.7

Weekly downloads
-
License
MIT
Repository
-
Last release
2 years ago

介绍

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-24248
disabledform全部禁用boolean选填false/truefalsetrue
required是否必填boolean选填false/truetruefalse
divider分割线内容string选填--基础信息
refVue组件的ref属性string----
message(0.3.3+)自定义校验必填时的错误提示string选填--姓名不能为空
minHeight(0.4.4+)elePlusForm最小高度string选填-200pxauto
maxHeight(0.4.4+)elePlusForm最大高度string选填--800px

Events

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

表单验证相关

参数说明类型可选值默认值举例
required表单项是否为必填booleantrue/falsetruefalse
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通过Vue3reactive方法自动生成表单项的默认值。

<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/truetrue
disabled禁用any/function/boolean选填false/truefalse0/true/(form) => state.disabled
show控制表单项显隐方法,接受function返回值为布尔类型function选填--(form) => form.type == 1
promptlabel后面的提示信息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
htmlhtml

三、输入框类

Attributes

参数说明类型是否必填可选值默认值举例
type表单项类型string必填input/number/integer/textarea/password/code (0.2.9+)-input
placeholder占位符string/function选填-根据lable自动生成请输入姓名
prependtype为input/number/integer类型是输入框前置内容string选填--¥
appendtype为input/number/integer类型是输入框后置内容string选填--
maxlength输入框类型表单项最大内容长度number选填-无限制200
rowstype为textarea时的行数number选填-46
mintype为textarea时的行数最小值number选填---
rule使用ElePlusForm内置校验规则string选填phone、idNumber、email、link-phone
time (0.2.9+)type为code时,验证码重新发送的时间number选填-6030
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) => {}
onChangechange事件(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必填--详见下方
placeholdertype为select时占位符string选填-type为select时根据lable自动生成根据lable自动生成
labelKeyoption为数组时,label的对应keystring选填-labelname
valueKeyoption为数组时,value的对应keystring选填-valueid
extraKey(0.4.80+)下拉框中额外展示的数据字段string选填--name
virtual(0.4.80+)下拉框是否开启虚拟列表,开启后,el-select将改为el-select-v2boolean选填-falsetrue

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

参数说明举例
onChangechange事件(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-
activeValueswitch 打开时的值boolean/string/number选填-true
inactiveValueswitch 关闭时的值boolean/string/number选填-false

Function

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

基础示例

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

参数说明举例
onChangechange事件(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

参数说明举例
onChangechange事件(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/textimage
max文件上传最多数量number选填-不限制
accept文件格式限制string选填同inputtype=file
accept属性image/*
multiple是否允许多选boolean选填false/truefalse
maxSize文件最大大小,单位Mnumber选填-不限制
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/truetruefalse
disabled禁用boolean选填false/truefalsetrue
itemSpan布局分栏number选填0-242412
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非必填-24vh40vh
selectable是否开启多选boolean非必填true/falsefalsetrue
max(0.4.9+)开启多选后,最大的选中数量number非必填-不限制5
rowKey(0.4.91+)开启多选后,行唯一标识,默认为value (*注:开启多选后,option中必须包含该字段)string开启多选后,必填-valueid

Function

参数说明举例
onChangechange事件(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表单项类型stringeditor-

Function

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

基础示例

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

十二、插槽slot

Attributes

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

基础示例

<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表单项类型stringhtml-

基础示例

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

2 years ago

0.7.7

2 years ago

0.7.2

2 years ago

0.7.4

2 years ago

0.7.5

2 years ago

0.7.1

2 years ago

0.7.0

2 years ago

0.6.9

2 years ago

0.6.7

2 years ago

0.6.6

2 years ago

0.6.8

2 years ago

0.6.81

2 years ago

0.6.3

2 years ago

0.6.2

2 years ago

0.6.5

2 years ago

0.6.4

2 years ago

0.6.1

2 years ago

0.5.8

2 years ago

0.5.7

2 years ago

0.5.9

2 years ago

0.6.0

2 years ago

0.5.4

2 years ago

0.5.3

2 years ago

0.5.6

2 years ago

0.5.5

2 years ago

0.5.2

2 years ago

0.5.1

2 years ago

0.4.40

3 years ago

0.4.41

3 years ago

0.4.9

3 years ago

0.4.8

3 years ago

0.4.31

3 years ago

0.4.32

3 years ago

0.4.30

3 years ago

0.3.8

3 years ago

0.3.7

3 years ago

0.4.21

3 years ago

0.4.999

3 years ago

0.4.97

3 years ago

0.4.98

3 years ago

0.4.95

3 years ago

0.4.96

3 years ago

0.4.93

3 years ago

0.4.94

3 years ago

0.4.91

3 years ago

0.4.92

3 years ago

0.4.99

3 years ago

0.4.5

3 years ago

0.4.4

3 years ago

0.4.7

3 years ago

0.4.6

3 years ago

0.4.1

3 years ago

0.4.0

3 years ago

0.4.3

3 years ago

0.4.2

3 years ago

0.4.80

3 years ago

0.4.73

3 years ago

0.4.71

3 years ago

0.4.72

3 years ago

0.4.70

3 years ago

0.5.0

3 years ago

0.4.64

3 years ago

0.4.65

3 years ago

0.4.62

3 years ago

0.4.63

3 years ago

0.4.60

3 years ago

0.3.93

3 years ago

0.4.61

3 years ago

0.3.92

3 years ago

0.3.9

3 years ago

0.3.91

3 years ago

0.4.66

3 years ago

0.4.52

3 years ago

0.4.50

3 years ago

0.3.64

3 years ago

0.3.63

3 years ago

0.3.62

3 years ago

0.3.61

3 years ago

0.3.60

3 years ago

0.3.6

3 years ago

0.3.53

3 years ago

0.3.52

3 years ago

0.3.56

3 years ago

0.3.55

3 years ago

0.3.54

3 years ago

0.3.51

3 years ago

0.3.31

3 years ago

0.3.33

3 years ago

0.3.32

3 years ago

0.3.42

3 years ago

0.3.41

3 years ago

0.3.43

3 years ago

0.3.5

3 years ago

0.3.4

3 years ago

0.3.3

3 years ago

0.3.13

3 years ago

0.3.12

3 years ago

0.3.11

3 years ago

0.3.22

3 years ago

0.3.21

3 years ago

0.3.0

3 years ago

0.2.7

3 years ago

0.2.6

3 years ago

0.2.9

3 years ago

0.2.8

3 years ago

0.3.2

3 years ago

0.3.1

3 years ago

0.2.5

3 years ago

0.1.20

3 years ago

0.1.21

3 years ago

0.1.22

3 years ago

0.1.11

3 years ago

0.1.23

3 years ago

0.1.12

3 years ago

0.1.24

3 years ago

0.1.13

3 years ago

0.1.25

3 years ago

0.1.14

3 years ago

0.1.15

3 years ago

0.1.0

3 years ago

0.2.1

3 years ago

0.2.0

3 years ago

0.1.1

3 years ago

0.1.16

3 years ago

0.1.17

3 years ago

0.1.18

3 years ago

0.1.19

3 years ago

0.2.2

3 years ago

0.2.4

3 years ago

0.0.1-beta

3 years ago