QForm

快捷表单，旨在优化element-plus表单开发过程的代码冗余，配置繁琐等问题。使用QForm，您可以快速完成表单页面的构建以及数据的收集、验证和提交。目前QForm已支持 输入类、选择类、 文本类 等19种的组件。

用法示例

基础用法

行内表单

对其方式、尺寸控制

栅格布局

表单校验

显隐控制

通过表单配置项 formOption 下的vIf,可以实现表单项的显隐控制。

vIf 类型为 boolean 或 一个返回boolean值方法， true 时显示，false 时隐藏。

{
  ...,
  vIf: (vals: any) => {
    // vals 为表单收集的数据对象
      return true
  }
}
// 或
{
  ...,
  vIf: true
}

1. 表单自身显隐控制

1. 外部控制表单显隐

只读表单

设置readonly 可开启表单只读模式

API

属性

以下是`` 新增属性，Element-Plus 的 Form 表单 原始配置均支持

属性名	说明	类型	默认值
model	表单数据对象	object	-
formOptions	表单项对象集合	FormItemRows[]	[]
required	是否为必填项，如不设置，则会根据校验规则确认	boolean	false
gutter	表单栅格间距	number	-
col	表单栅格占据的列数，配置后会开起栅格布局，默认不开启	number	-
readonly	是否只读	boolean	false
buttons	默认按钮组集合 默认支持按钮 search 、reset、cancel、submit 对应四种触发事件 button配置	BtnTypeObj	-

表单项对象属性

属性名	说明	类型	是否比填
type	表单组件类型	CompTypes
label	表单项文本	string |() => VNode	是
prop	属性名	string	是
required	是否必填，可动态控制，设置为function时，values返回当前Form搜集的值	boolean/ Function	否
vIf	是否显示表单项，默认true，设置为function时，values返回当前Form搜集的值	boolean / Function	否
formItem	element-plus【form-item】相关配置		否
options	选择类组件选项配置，形式如：[{label:xxx,value:xxx}]	ItemOptions	否
col	表单栅格占据的列数	number	否
attrs	type 对应原始组件的属性及方法	object	否

事件

事件名	说明	类型
search	点击默认支持按钮 search 时触发	Function
reset	点击默认支持按钮 reset 时触发	Function
cancel	点击默认支持按钮 cancel 时触发	Function
submit	点击默认支持按钮 submit 时触发	Function
validate	任一表单项被校验后触发	Function
change	任一表单项被改变后触发 value 改变之后的值， prop 当前触发的表单项绑定的prop值	Function
input	输入型表单项在 Input 值改变时触发	Function
blur	当具备 Blur 事件的任一表单项失去焦点时触发	Function
focus	当具备 Focus 事件的任一表单项获得焦点时触发	Function
clear	在点击由 clearable 属性生成的清空按钮时触发	Function
expand-change	当展开节点发生变化时触发，主要针对``type 类型为cascader` 的组件触发
visible-change	下拉框出现/隐藏时触发，主要针对type 类型为cascader、select、select-v2、time-picker做的组件触发	l
remove-tag	在多选模式下，移除Tag时触发，主要针对type 类型为cascader、select、select-v2做的组件触发
active-change	面板中当前显示的颜色发生改变时触发，主要针对type 类型为color-picker做的组件触发

方法

名称	说明	类型
validate	对整个表单的内容进行验证。 接收一个回调函数，或返回 Promise。	Function
validateField	验证具体的某个字段。	Function
resetFields	重置该表单项，将其值重置为初始值，并移除校验结果	Function
scrollToField	滚动到指定的字段	Function
clearValidate	清理某个字段的表单验证信息。	Function

插槽

事件名	说明
default	自定义按钮区域内容
[prop]	options中配置任一表单项对象中的prop

button配置

按钮类型	触发对应事件
search	search
reset	reset
cancel	cancel
submit	submit

支持的组件类型

组件类型

类型	对应Element-Plus组件	说明
input	Input 输入框
textarea	Input 文本域
input-number	Input Number 数字输入框
radio	Radio 单选框
checkbox	Checkbox 多选框
select	Select 选择器
select-v2	Virtualized Select 虚拟化选择器
cascader	Cascader 级联选择器
tree-select	TreeSelect 树形选择
time-select	TimeSelect 时间选择
date-picker	DatePicker 日期选择器 DateTimePicker 日期时间选择器	支持Element-Plus两种组件，通过组件自身的type可配置选择器类型
time-picker	TimePicker 时间选择器
rate	Rate 评分
color-picker	ColorPicker 颜色选择器
slider	Slider 滑块
switch	Switch 开关
text	-	渲染普通文本
html	-	渲染html片段
slot	-	自定义表单组件

类型申明

类型申明

type CompTypes = "input" | 'textarea' | "input-number" | "select" | "select-v2" | "cascader" | "radio" | "checkbox" | "tree-select" | "time-select" | "date-picker" | "time-picker" | "color-picker" | "rate" | "slider" | "switch" | "text" | "html" | "slot";

type FormItemRows<T extends CompTypes = CompTypes> = {
    type: T;
    label: string | (() => VNode);
    prop: string;
    col?: number;
    required?: boolean | ((formValue: Indexable) => boolean);
    options?: Array<ItemOptions>;
    formItem?: Partial<FormItemProps> & Indexable;
    attrs?: (T extends keyof CompPropsMap ? CompPropsMap[T] : Indexable); //原始 CompTypes 组件属性及方法
    vIf?: boolean | ((formValue: Indexable) => boolean);
}

type BtnType = "search" | "reset" | "cancel" | "submit";
type BtnTypeRow = {
    label: string;
    type: BtnType;
    icon?: string;
}
type BtnTypeUnit = BtnTypeRow | BtnType;

type ItemOptions = {
    label: string;
    value: Numeric;
    children?: Array<ItemOptions>;
} & Indexable