FirstUI UNI版

Form 表单校验 VIP专属

概述

Form 表单校验，提供了常用的表单校验方法，支持传入自定义校验方法，自带错误消息提示。

# 支持平台

App-vue App-Nvue 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序 H5 PC 快手小程序 钉钉小程序
✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

# 引入

以下介绍两种常用的引入方式。
第一种：在页面中引用、注册
import fuiForm from "@/components/firstui/fui-form/fui-form.vue"
export default {
	components:{
		fuiForm
	}
}
1
2
3
4
5
6
第二种：easycom组件规范
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。

First UI easycom配置请查看 快速上手。

如果不了解easycom，可先查看 官网文档 (opens new window)。

# 代码演示

部分示例演示，完整使用请参考示例程序以及文档API。
基础使用

通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.form访问到对应的组件实例，并调用上面的实例方法。

<fui-form ref="form">
	<fui-input required label="姓名" borderTop placeholder="请输入姓名" v-model="formData.name"></fui-input>
	<fui-input required label="手机号" placeholder="请输入手机号码" v-model="formData.mobile"></fui-input>
	<view class="fui-btn__box">
		<fui-button text="Submit" bold @click="submit"></fui-button>
	</view>
</fui-form>
1
2
3
4
5
6
7
//校验规则
const rules = [{
	name: "name",
	rule: ["required"],
	msg: ["请输入姓名"]
}, {
	name: "mobile",
	rule: ["required", "isMobile"],
	msg: ["请输入手机号", "请输入正确的手机号"]
}];

//表单data数据
formData: {
	name: '',
	mobile: ''
}

//methods
submit() {
	console.log(this.formData)
	this.$refs.form.validator(this.formData, rules).then(res => {
		console.log(res)
		if (res.isPassed) {
			this.fui.toast('校验通过！')
		}
	}).catch(err => {
		console.log(err)
	})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# Slots

插槽名称 说明
default 组件内部内容，由多个表单组件组成

# Props

属性名 类型 说明 默认值 平台差异说明
model V2.1.0+ Object 表单数据，格式 {key:value,key:value}，结合FormItem组件校验时必传 { } -
padding Array 表单外层padding值（上，右，下，左），同css顺序,如：['32rpx','32rpx'] [ ] -
show Boolean 是否显示校验错误信息，设置false时，可结合formItem组件显示校验信息 true -
disabled Boolean 是否禁用该表单内的所有组件,透明遮罩层 false -
top Number, String 错误提示框top值，单位：px 0 H5端默认为44(px),如果未使用默认导航栏，需要将top值设置为0
left Number, String 错误提示框left值，单位：rpx 24 -
right Number, String 错误提示框right值，单位：rpx 24 -
background String 错误提示框背景色 #FF2B2B 非Nvue端默认值为空，可通过css变量（--fui-color-danger）改变背景颜色
size Number,String 错误提示文本字体大小，单位rpx 28 -
color String 错误提示文本字体颜色 #fff -
radius Number, String 错误提示框圆角值，单位rpx 16 -
duration Number 错误提示框单次显示时间，单位ms 2000 -
labelSize V1.8.0+ Number, String FormItem 组件标题字体大小，单位rpx，默认使用全局设置值 0 -
labelColor V1.8.0+ String FormItem 组件标题字体颜色 #333 -
labelWidth V1.8.0+ Number, String FormItem 组件label宽度，单位rpx，默认使用全局设置值 0 -
labelAlign V1.9.0+ String FormItem 组件label对齐方式，可选值：left，right left -
labelWeight V1.9.8+ Number,String FormItem 组件label字重，同font-weight，默认使用全局设置值 0 -
asteriskColor V1.8.0+ String FormItem 组件星号颜色 #FF2B2B -
asteriskPosition V1.9.0+ String FormItem 组件星号位置，可选值：left，right left -
errorPosition V2.1.0+ Number,String FormItem 组件错误提示定位方式方式：1-absolute 2-relative 1 -
errorAlign V2.1.0+ String FormItem 组件错误提示显示对齐方式，可选值：left、center、right center -

# Events

事件名 说明 回调参数
- - -

# Methods

通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。

方法名 说明 传入参数 返回参数
validator 表单验证方法 model : Object 表单数据
rules : Array 校验规则数据
checkAll : 是否校验所有元素		 {
  isPassed : 是否验证通过
   errorMsg : 错误消息
}
validateField V2.2.0+ 验证具体的一个或多个字段 props : Array/String 字段
model : Object 表单数据
rules : Array 校验规则数据		 {
  isPassed : 是否验证通过
   errorMsg : 错误消息
}
clearValidate V2.2.0+ 清除校验错误信息，仅结合FormItem组件显示校验信息时有效 props : Array 或 String 字段 -
resetFormItemParam V2.1.0+ 通知FormItem组件重置props参数 - -
switchRealTimeValidator V2.1.0+ 通知FormItem组件开启或关闭实时校验，结合FormItem组件校验时有效 isOpen : Boolean 是否开启实时校验
rules : Array 校验规则数据 		-
//方法及参数详细说明

/*
 单校验方法参数详细说明
 @param model {Object} 表单数据对象，传null则使用属性model值
 @param rules {Boolean} 表单验证规则，当传null 或空数组时使用FormItem组件内rules（V2.2.0+支持）
 @param checkAll  {Boolean} 是否校验所有元素 （V1.7.0+ 支持），注意：结合FormItem组件显示校验提示时必须传true
*/
validator: function(model, rules, checkAll = false)

/*
=======================
model：Object 表单数据，格式 {key:value,key:value}

rules：Array<Object> 校验规则数据，格式 [{name:value,rule:[],msg:[],validator:[]}]
      -------------------
	  name：String，元素的名称，与model中key一致
	  rule：Array<String> ，内置的校验方法名称集合，详细见下方说明
	  msg：Array<String>，对应rule规则方法的错误提示信息
	  validator：Array<Object>，自定义校验方法集合，格式 [{msg:'出错后提示信息',method:Function 校验法法}]
	            -----------
				method：校验方法约定必须返回 true 或 false 作为校验结果
				
checkAll：Boolean 是否校验所有元素并返回所有错误信息，结合FormItem组件显示校验提示时必须传true。（V1.7.0+ 支持）
=======================
*/


// rule 内置校验方法名称详细说明。组合使用，如：['required','isMobile']
/*
=======================
required：必填项。非必填情况下，如果值为空则不进行校验
isMobile：是否为手机号码
isEmail：是否为邮箱
isCarNo：是否为车牌号
isIdCard：是否为身份证号
isAmount：是否为金额，允许保留两位小数
isNumber：是否为数字
isChinese：是否全为中文
isNotChinese：是否不包含中文，可以有特殊字符
isEnglish：是否为英文
isEnAndNo：是否为英文和数字组合 4~30 位
isEnOrNo：只包含英文或者数字
isSpecial：是否有特殊字符，若有则返回false
isEmoji：是否有表情符号，若有则返回false
isDate：是否为日期：2021-08-09
isUrl：是否为URL地址
isSame：与某个key值是否相同，传值：'isSame:key'，不相同则返回false
range：数值范围，传值：'range:[1,9]'
minLength：最小长度，传值：'minLength:Number'，如：'minLength:1'
maxLength：最大长度，传值：'maxLength:Number'，如：'maxLength:149'
isKeyword：是否包含关键词，多个以英文逗号分隔，包含则返回false。传值：'isKeyword:key1,key2'
=======================
*/



/**
 * 验证具体的一个或多个字段（V2.2.0+）
 * @param {Array<string> ｜ String} props 字段key，传值格式如：'name' 或 ['name','mobile']
 * @param {Object} model 表单数据对象，传null则使用属性中model值
 * @param {Array} rules 表单验证规则，当传null 或空数组时使用FormItem组件内rules
 */
validateField(props, model, rules) 



/**
 * 清除校验错误信息，仅结合FormItem组件显示校验信息时有效（V2.2.0+）
 * @param {Array<string> ｜ String} props 字段key，不传则清除所有校验信息，传值格式如：'name' 或 ['name','mobile']
 */
clearValidate(props = [])



/*
 通知FormItem组件重置props参数 [V2.1.0+]
*/
resetFormItemParam: function()


/*
 通知FormItem组件开启或关闭实时校验，结合FormItem校验时有效（开启时，当前item项内容改变即校验） [V2.1.0+]
 @param isOpen {Boolean} 是否开启实时校验
 @param rules {Array} 表单验证规则，数据同上validator方法中rules，当isOpen为true时必传
*/
switchRealTimeValidator: function(isOpen, rules = [])
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

TIP V2.1.0+

组件校验信息默认使用顶部弹出方式显示，当结合FormItem组件显示错误信息需要注意：

  • fui-form-item 组件 必须设置 prop 属性
  • fui-form 组件必须设置 model 属性，且 show 属性必须设为false
  • fui-form 组件 validator 方法第三个参数必须传true
  • 当 属性 errorPosition 值设置为 1 时，注意控制提示内容文本长度，建议不要超过一行，开发时请自行注意，若提示内容过长请将属性值设置为 2

示例预览

# 示例代码地址

VIP内容代码请查看订单页下载的组件库示例源码。

# 特别说明

该组件为付费组件，UNI-APP版VIP用户可免费使用 。

开通会员 (opens new window)

Last Updated: 11/9/2023, 10:53:13 AM

← FormItem 表单项 →