QilinForm组件

QilinForm组件用于表单，基于element-plus的el-form组件封装。

注意

1、若表单内级联组件必填，则trigger触发方式须填change或含change。

基本使用

<template>
    <QilinForm v-model:formConfig="formConfig" ref="formConfigRef">
        <template v-slot:projectIntroduce="slotData">
            <el-form-item :label="slotData.data.item.labelName" :prop="slotData.data.item.dataName"
                :style="slotData.data.item.style"
            >
                <el-input v-model="formConfig.submitData[slotData.data.item.dataName]"
                    placeholder="请输入项目介绍！！"
                ></el-input>
            </el-form-item>
        </template>
        <template v-slot:evaluation="slotData">
            <el-input v-model="formConfig.submitData[slotData.data.item.dataName]"
                placeholder="请输入个人评价~~~"
            ></el-input>
        </template>
        <template v-slot:extraFormItem>
            <el-form-item label="年收入" prop="salary" style="width:100%">
                <el-input v-model="formConfig.submitData.salary" placeholder="分逼不挣"></el-input>
            </el-form-item>
        </template>
        <template v-slot:extraItem>
            <div>这是独立于form表单之外的元素，常用于一些项目的额外奇葩的需求实现！</div>
        </template>
    </QilinForm>
</template>

<script setup>
import {reactive,ref,onMounted} from "vue";

// 获取提交表单元素DOM
const formConfigRef=ref(null);

/*
    逻辑脚本代码区域
*/
const changeProjectName=(item,index,info)=>{
    // console.log(item,index,info);
};

const formConfig=reactive({
    elFormConfig:{
        labelWidth:"100px",
        // labelSuffix:"：",
        border:true,
        validateOnRuleChange:false
    },
    itemConfig:[
        {
            hideLabel:false,
            labelName:"简介",
            dataName:"description",
            type:"input",
            inputType:"textarea",
            maxlength:300,
            rows:3,
            width:24,
            itemStyle:"color:red;"
        },
        {
            labelName:"身份证号码",
            dataName:"idCard",
            type:"input",
            inputType:"number",
            width:12,
            otherValidate:"idCardValidator"
        },
        {
            labelName:"手机号码",
            dataName:"phonenumber",
            type:"input",
            inputType:"text",
            width:12,
            otherValidate:"phoneValidator"
        },
        {
            labelName:"出生日期",
            dataName:"birthday",
            type:"date",
            dateType:"date",
            format:"YYYY-MM-DD",
            valueFormat:"YYYY-MM-DD",
            defaultValue:new Date(2000,1,1),
            width:12
        },
        {
            labelName:"年龄",
            dataName:"age",
            type:"number",
            width:12
        },
        {
            labelName:"性别",
            dataName:"gender",
            type:"select",
            dataListName:"genderList",
            width:12
        },
        {
            labelName:"参与项目",
            dataName:"projectName",
            type:"cascader",
            dataListName:"projectNameList",
            filterable:true,
            cascaderProps:{
                label:"name",
                value:"id",
                children:"children",
                multiple:true
            },
            change:changeProjectName,
            style:"width:100%",
            width:12
        },
        {
            labelName:"项目介绍",
            hideLabel:true,
            dataName:"projectIntroduce",
            type:"itemSlot",
            slotName:"projectIntroduce",
            style:"width:50%;",
            width:12
        },
        {
            labelName:"个人评价",
            dataName:"evaluation",
            type:"slot",
            slotName:"evaluation",
            width:12
        }
    ],
    selectLists:{
        genderList:[
            {
                label:"男",
                value:0
            },
            {
                label:"女",
                value:1
            },
            {
                label:"人妖",
                value:2
            }
        ],
        projectNameList:[
            {
                name:"南京冠霆智能科技有限公司",
                id:1,
                children:[
                    {
                        name:"看守所项目",
                        id:11
                    },
                    {
                        name:"拘留所项目",
                        id:12
                    },
                    {
                        name:"戒毒所项目",
                        id:13
                    },
                    {
                        name:"安康医院项目",
                        id:14
                    }
                ]
            },
            {
                name:"亚信安全有限公司",
                id:2,
                children:[
                    {
                        name:"亚信智网有限公司",
                        id:21,
                        children:[
                            {
                                name:"SDP零信任项目",
                                id:211
                            },
                            {
                                name:"动态应用安全防护系统BSG",
                                id:212
                            }
                        ]
                    }
                ]
            },
            {
                name:"苏软科技（南京）有限公司",
                id:3,
                children:[
                    {
                        name:"云上贵州项目",
                        id:31
                    },
                    {
                        name:"红花街道h5项目",
                        id:32
                    },
                    {
                        name:"温州市党政机关信息化项目",
                        id:33
                    }
                ]
            },
            {
                name:"南京联创智慧城市科技有限公司",
                id:4,
                children:[
                    {
                        name:"U创办公管理系统",
                        id:41
                    },
                    {
                        name:"U创办公小程序",
                        id:42
                    }
                ]
            }
        ]
    },
    buttonConfig:[
        {
            btnName:"重置",
            btnType:"default",
            btnSize:"default",
            isHideFn:(item)=>{
                return true;
            },
            formRefName:formConfigRef,
            btnClick:(formRef)=>{
                formRef.formResetFields();
            }
        },
        {
            btnName:"修改",
            btnType:"primary",
            btnSize:"default",
            isHide:true,
            formRefName:formConfigRef,
            btnClick:(formRef)=>{

            }
        },
        {
            btnName:"提交",
            btnType:"primary",
            btnSize:"default",
            formRefName:formConfigRef,
            btnClick:(formRef)=>{
                formRef.formValidate((valid)=>{
                    if(valid){
                    }
                })
            }
        },
    ],
    submitData:{
        description:"",
        idCard:"",
        phonenumber:"",
        birthday:"",
        age:0,
        gender:0,
        projectName:"",
        projectIntroduce:"",
        evaluation:"",
        salary:""
    }
});


/*
    生命周期等代码区域
*/


</script>

示例：

Props参数

formConfig object

核心配置项，支持以下参数。

属性名	类型	说明	可选值	默认值
elFormConfig	object	el-form标签元素上的相关配置，详见elFormConfig	-	-
itemConfig	array	表单内每个组件的配置项，详见itemConfig	-	-
selectLists	object	下拉数据集，详见selectLists	-	-
buttonConfig	array	表单内的按钮配置项，详见buttonConfig	-	-
submitData	object	提交到后台的数据集，详见submitData	-	-

elFormConfig object

el-form标签元素上的相关配置

属性名	类型	说明	可取值	默认值
labelWidth	string/number	label标签的长度	-	60px
labelPosition	string	label标签的位置	left/right/top	left
labelSuffix	string	label标签的后缀	-	：
size	string	表单内组件的尺寸	large/small/default	default
className	string	el-form的自定义类名	-	-
style	object/string	最外层元素即QilinForm元素的自定义行内样式	-	-
border	boolean	是否将表单元素转为表格样式	-	false
borderColor	string	表格样式的边框颜色	-	#E9E9E9
validateOnRuleChange	boolean	是否在表单验证规则发生变化时重新触发表单验证	-	false

itemConfig object

表单内每个组件的配置项。

属性名	类型	说明	可取值	默认值
labelName	string	label标签的文字	-	默认名称
dataName	string	对应后台的数据字段名	-	-
isHide	boolean	是否隐藏该表单项	-	false
hideLabel	boolean	是否隐藏该表单项的label标签	-	false
labelNameText	string	label标签的额外字段	-	-
type	string	表单组件的类型	input/number/select/radio/checkbox/date/upload/cascader/rate/switch/image/wangEditor/vueEditor/kaitifytext/slot/itemSlot	input
inputType	string	input的类型，当且仅当type=input时生效	text/password/textarea/number	text
showPassword	boolean	是否显示切换密码图标，当且仅当inputType=password时生效	-	false
autocomplete	string	是否启用表单自动完成的功能，当且仅当type=input时生效，设置为off即关闭自动填充（有些浏览器并不生效，测试设置为new-password即可）	on/off/new-password/new-text/...	new-text
clearable	boolean	是否显示可以一键清空按钮	-	true
rows	number	行高，当且仅当inputType=textarea时生效	-	2
number	number	当输入框为数字输入框时，允许输入的整数位数，当inputType=number或者inputType=true时生效，你也可以直接在项目中用此指令v-number	-	-
decimal	number	当输入框为数字输入框时，允许输入的小数位数，当inputType=number或者inputType=true时生效	-	-
maxlength	number	最大输入长度，当inputType为text、textarea、password时生效	-	-
minlength	number	最小输入长度，当inputType为text、textarea、password时生效	-	-
prefixIcon	string	输入框前置内置图标，当且仅当type=input时生效	-	-
prefixSlotName	string	输入框前置内置图标插槽名称，当且仅当type=input时生效	-	-
suffixIcon	string	输入框后置内置图标，当且仅当type=input时生效	-	-
suffixSlotName	string	输入框后置内置图标插槽名称，当且仅当type=input时生效	-	-
max	number	最大输入数字，当且仅当type=number时生效	-	-
min	number	最小输入数字，当且仅当type=number时生效	-	-
rateSize	string	评分组件的尺寸，当且仅当type=rate时生效	large/small/default	default
allowHalf	boolean	是否允许半选，当且仅当type=rate时生效	-	false
dataListName	string	下拉数据名称对应selectLists中属性名，当type=select、cascader、checkbox、radio时生效	-	-
multiple	boolean	是否可以多选，当type=select、checkbox时生效	-	false
collapseTags	boolean	多选时是否将选中值按文字的形式展示，当type=select时生效	-	false
filterable	boolean	是否可搜索，当type为select	cascader时生效,cascader时默认为false	-
cascaderProps	object	配置级联选择器的选项，具体的配置参数详见element官网el-cascader文档，当type=cascader时生效	-	-
customLabelName	string	下拉选项中自定义label对应字段值，当type=select、radio、checkbox时生效	-	label
customValueName	string	下拉选项中自定义value对应字段值，当type=select、radio、checkbox时生效	-	value
loading	boolean	是否正在从远程获取数据，当type=select时生效	-	false
remote	boolean	其中的选项是否从服务器远程加载，当type=select时生效	-	false
remoteMethod	function	定义远程搜索方法，启用远程搜索需要开filterable和remote设置为true，当type=select时生效	-	-
dateType	string	日期选择器的类型，当type=date时生效	year/years/month/date/dates/datetime/week/datetimerange/daterange/monthrange	date
defaultTime	Date/[Date,Date]	选择日期后的默认时间值，默认8点半，当type=date且为范围选择时生效	-	new Date(2000,1,1,8,30,0)
defaultValue	Date/[Date,Date]	选择器打开时默认显示的时间	-	-
format	string	显示在输入框中的格式化时间设置，当type=date时生效	-	YYYY-MM-DD HH:mm:ss
valueFormat	string	传给后台的格式化时间设置，当type=date时生效	-	YYYY-MM-DD HH:mm:ss
startPlaceholder	string	日期开始提示语，当type=date且dateType=***range时生效	-	-
endPlaceholder	string	日期结束提示语，当type=date且dateType=***range时生效	-	-
timeFormat	string	时间选择器时分秒下拉列表中显示的时间格式，当type=date时生效	-	HH:mm:ss
rangeSeparator	string	时间选择器的范围分隔符，当type=date且dateType=***range时生效	-	至
switchSize	string	开关组件的尺寸，当type=switch时生效	large/small/default	default
activeText	string	开关打开时的文字描述，当type=switch时生效	-	-
inactiveText	string	开关关闭时的文字描述，当type=switch时生效	-	-
activeValue	string	开关打开时的值，当type=switch时生效	-	-
inactiveValue	string	开关关闭时的值，当type=switch时生效	-	-
inlinePrompt	boolean	switch时图标或文字是否显示在开关内，当type=switch时生效	-	false
width	string	表单每项组件的栅栏占比宽度	6/8/12/16/18/24	24
className	string	表单每项组件即el-form-item的自定义类名	-	-
itemStyle	string	表单每项组件即el-form-item的自定义样式	-	-
disabled	boolean	是否禁用该项	-	false
slotName	string	slot具名插槽名称，当type=slot时生效	-	-
style	string	额外的行内样式，当type=input/select/cascader/radio/switch/checkbox时生效	-	-
dateWidth	string	date组件元素的长度，默认为auto，当type=date时生效	-	auto
placeholder	string	表单占位符提示语	-	-
validate	array	表单的简单校验规则，取值为对象数组	-	-
otherValidate	string	Qilin表单组件的内置校验规则	emailValidator/phoneValidator/idCardValidator	-
change	function	change事件	(item,val)=>{}	-
clear	function	clear事件，当type=input、select时生效	(item)=>{}	-
customFn	function	自定义事件，当type=image、upload且无指定action时生效，主要用于上传文件时手动即时上传文件至服务器	(item,file)=>{}	-

selectLists object

下拉数据集，当type=select、checkbox、radio、cascader时其内属性名须对应dataListName的值。

buttonConfig array

表单底部操作提交按钮相关配置项。

属性名	类型	说明	可取值	默认值
btnName	string	按钮名称	-	按钮
btnType	string	按钮类型	primary/success/warning/danger/info/text	default
btnSize	string	按钮尺寸	large/small/default	default
className	string	按钮自定义类名	-	-
formRefName	DOM	表单元素的DOM	-	-
btnClick	function	按钮点击事件	(formRef,event)=>{}	-
buttonConfigClassName	string	表单底部按钮外父元素自定义类名	-	-

submitData object

提交到后台的数据集，即每个itemConfig的dataName值组成的对象。

Events

组件的暴露事件。

事件名	类型	参数	说明
-	function	item,value\event\undefined,undefined\ref	每个itemConfig表单元素的change、blur、clear等事件，配置在itemConfig中，事件名就是他们的属性名，如change

Exposes

组件的暴露方法。

方法名	类型	参数	说明
formValidate	function	valid	对整个表单的内容进行验证，接受一个回调函数或返回Promise
formResetFields	function	props/undefined	重置该表单项，将其值重置为初始值，并移除校验结果，未指定字段的话就是重置整个表单
formClearValidate	function	props/undefined	清理某个字段的表单验证信息，未指定字段的话就是清理整个表单
formValidateField	function	props	对单个表单项进行校验
createFormRules	function	-	用于创建表单的校验规则，用于在更新表单校验规则后触发该方法，解决校验规则更新不成功的问题

Slots

组件的插槽。

插槽名	数据值	说明
{item.slotName}	data:{scope,item}	设置itemConfig配置项中的type为slot或者itemSlot时即可使用，用于需要对元素某项进行特殊处理的需求，其中设置的slotName属性值就是该插槽名
extraFormItem	-	用于需要自定义表单插槽，该插槽位置在所有表单项之后
extraItem	-	用于需要自定义表单之外的插槽，该插槽位置在表单元素之后