此组件一般用于表单场景,可以配置Input输入框,Select弹出框,进行表单验证等。
注意:
由于在nvue
下,u-form
名称被uni-app官方占用,在nvue
页面中请使用u--form
名称,在vue
页面中使用u--form
或者u-form
均可。
注意:
需要兼容微信小程序,并且校验规则中含有方法等,只能通过setRules方法设置规则。 如。
onReady() {
//onReady 为uni-app支持的生命周期之一
this.$refs.uForm.setRules(this.rules)
},
copy
App(vue) | App(nvue) | H5 | 小程序 |
---|---|---|---|
√ | √ | √ | √ |
此组件一般是用于表单验证使用,每一个表单域由一个u-form-item
组成,表单域中可以放置u-input
、u-checkbox
、u-radio
、u-switch
等。
model
参数绑定一个对象,这个对象的属性为各个u-form-item
内组件的对应变量。ref
操作,故这里需要给form
组件声明ref="uForm"
属性。u-from-item
内其他可能包含的诸如input
、radio
等组件,请见各自组件的相关文档说明。<template>
<view>
<!-- 注意,如果需要兼容微信小程序,最好通过setRules方法设置rules规则 -->
<u--form
labelPosition="left"
:model="model1"
:rules="rules"
ref="uForm"
>
<u-form-item
label="姓名"
prop="userInfo.name"
borderBottom
ref="item1"
>
<u--input
v-model="model1.userInfo.name"
border="none"
></u--input>
</u-form-item>
<u-form-item
label="性别"
prop="userInfo.sex"
borderBottom
@click="showSex = true; hideKeyboard()"
ref="item1"
>
<u--input
v-model="model1.userInfo.sex"
disabled
disabledColor="#ffffff"
placeholder="请选择性别"
border="none"
></u--input>
<u-icon
slot="right"
name="arrow-right"
></u-icon>
</u-form-item>
</u--form>
<u-action-sheet
:show="showSex"
:actions="actions"
title="请选择性别"
description="如果选择保密会报错"
@close="showSex = false"
@select="sexSelect"
>
</u-action-sheet>
</view>
</template>
<script>
export default {
data() {
return {
showSex: false,
model1: {
userInfo: {
name: 'uView UI',
sex: '',
},
},
actions: [{
name: '男',
},
{
name: '女',
},
{
name: '保密',
},
],
rules: {
'userInfo.name': {
type: 'string',
required: true,
message: '请填写姓名',
trigger: ['blur', 'change']
},
'userInfo.sex': {
type: 'string',
max: 1,
required: true,
message: '请选择男或女',
trigger: ['blur', 'change']
},
},
radio: '',
switchVal: false
};
},
methods: {
sexSelect(e) {
this.model1.userInfo.sex = e.name
this.$refs.uForm.validateField('userInfo.sex')
},
},
onReady() {
//如果需要兼容微信小程序,并且校验规则中含有方法等,只能通过setRules方法设置规则。
this.$refs.uForm.setRules(this.rules)
},
};
</script>
copy
从上面的示例我们可以看到,rules
中的属性名和form
的属性名是一致的,同时传递给u-form-item
的prop
参数绑定的也是相同的属性名,注意这里prop
参数绑定的是 字符串(属性名),而不是一个变量。
此组件一般需要搭配Form
组件使用,也可以单独搭配Input
等组件使用,由于此组件参数较多,这里只对其中参数最简要介绍,其余请见底部的API说明:
prop
为传入Form
组件的model
中的属性字段,如果需要表单验证,此属性是必填的。labelPosition
可以配置左侧"label"的对齐方式,可选为left
和top
。borderBottom
是否显示表单域的下划线,如果给Input
组件配置了边框,可以将此属性设置为false
,从而隐藏默认的下划线。leftIcon
和rightIcon
参数实现。组件验证部分采用了async-validator?(opens new window),一个字段可以设置多个内置规则,以及自定义规则,触发方式等, 每个字段的验证规则为一个数组,数组的每一个元素对象为其中一条规则(一个字段的验证可以配置多个规则),如下:
rules: {
'userInfo.name': {
type: 'string',
required: true,
message: '请填写姓名',
trigger: ['blur', 'change']
},
code: {
type: 'string',
required: true,
len: 4,
message: '请填写4位验证码',
trigger: ['blur']
},
'userInfo.sex': {
type: 'string',
max: 1,
required: true,
message: '请选择男或女',
trigger: ['blur', 'change']
},
radiovalue1: {
type: 'string',
min: 1,
max: 2,
message: '生命是美好的,请不要放弃治疗',
trigger: ['change']
},
checkboxValue1: {
type: 'array',
min: 2,
required: true,
message: '不能太宅,至少选两项',
trigger: ['change']
},
intro: {
type: 'string',
min: 3,
required: true,
message: '不低于3个字',
trigger: ['change']
},
hotel: {
type: 'string',
min: 2,
required: true,
message: '请选择住店时间',
trigger: ['change']
},
'userInfo.birthday': {
type: 'string',
required: true,
message: '请选择生日',
trigger: ['change']
},
},
copy
每一个验证规则中,可以配置多个属性,下面对常用的属性进行讲解,更具体的可以查看async-validator?(opens new window)的文档说明:
trigger
{String | Array}:触发校验的方式有2种:
['change', 'blur']
type
{String}
内置校验规则,如这些规则无法满足需求,可以使用正则匹配、或者使用validator
自定义方法并结合uView自带验证规则。
string
?类型,默认类型number
?类型boolean
?类型function
?类型regexp
?类型,这里的正则,指的是判断字段的内容是否一个正则表达式,而不是用这个正则去匹配字段值整数
类型浮点数
类型array
?类型object
?类型enmu
?指定的值中date
?类型url
?类型16
?进制类型email
?类型required
布尔值,是否必填,配置此参数不会显示输入框左边的必填星号,如需要,请配置u-form-item
的required
为true
,注意:如需在swiper
标签内显示星号,需要给予swiper-item
第一个根节点一定的margin
样式
pattern
要求此参数值为一个正则表达式,如: /\d+/,不能带引号,如:"/\d+/",组件会对字段进行正则判断,返回结果。
min
最小值,如果字段类型为字符串和数组,会取字符串长度与数组长度(length)与min
比较,如果字段是数值,则直接与min
比较。
max
最大值,规则同min
参数
len
指定长度,规则同min
,优先级高于min
和max
enum
{Array} 指定的值,配合 type: 'enum' 使用
whitespace
{Boolean}
如果字段值内容都为空格,默认无法通过required: true
校验,如果要允许通过,需要将此参数设置为true
transform
{Function},校验前对值进行转换,函数的参数为当前值,返回值为改变后的值,参数如如下:
value
:当前校验字段的值message
校验不通过时的提示信息
validator
{Function}:自定义同步校验函数,参数如下:
rule
:当前校验字段在 rules 中所对应的校验规则value
:当前校验字段的值callback
:校验完成时的回调,一般无需执行callback,返回true
(校验通过)或者false
(校验失败)即可asyncValidator
{Function}:自定义异步校验函数,参数如下:
rule
:当前校验字段在 rules 中所对应的校验规则value
:当前校验字段的值callback
:校验完成时的回调,执行完异步操作(比如向后端请求数据验证),如果不通过,需要callback(new Error('提示错误信息')),如果校验通过,执行callback()即可uView在JS板块的Test 规则校验中有大量内置的验证规则,这些规则对表单验证来说,属于自定义规则,故需要用到上方规则属性的?validator
自定义验证函数,这里做一个详细说明。
我们知道uView有自带的判断手机号的验证方法uni.$u.test.mobile(value)
,但是async-validator?(opens new window)没有 内置判断手机号的规则,所以将二者结合使用:
rules: {
// 字段名称
mobile: [
{
required: true,
message: '请输入手机号',
trigger: ['change','blur'],
},
{
// 自定义验证函数,见上说明
validator: (rule, value, callback) => {
// 上面有说,返回true表示校验通过,返回false表示不通过
// uni.$u.test.mobile()就是返回true或者false的
return uni.$u.test.mobile(value);
},
message: '手机号码不正确',
// 触发器可以同时用blur和change
trigger: ['change','blur'],
}
]
}
copy
上面讲述了async-validator?(opens new window)的规则和配置,以及uView内置规则的结合使用,下面我们进行一个综合 实战示例,要入对某一个字段进行如下验证(验证实现有多种方法,下方仅为引导示例,非唯一,或最优做法):
change
和blur
触发校验:配置required
参数为true
,同时配置trigger
为[change, blur]
pattern
参数配置正则:/^[0-9a-zA-Z]*$/g,通过transform
参数在校验前对字段值转换为字符串min
为6,max
为8uni.$u.test.contains()
方法,并结合validator
自定义函数实现asyncValidator
异步函数进行验证。综上,我们可以得出如下的一个配置规则(仅为综合演示,非最优做法):
rules: {
name: [
// 必填规则
{
required: true,
message: '此为必填字段',
// blur和change事件触发检验
trigger: ['blur', 'change'],
},
// 正则判断为字母或数字
{
pattern: /^[0-9a-zA-Z]*$/g,
// 正则检验前先将值转为字符串
transform(value) {
return String(value);
},
message: '只能包含字母或数字'
},
// 6-8个字符之间的判断
{
min: 6,
max: 8,
message: '长度在6-8个字符之间'
},
// 自定义规则判断是否包含字母"A"
{
validator: (rule, value, callback) => {
return uni.$u.test.contains(value, "A");
},
message: '必须包含字母"A"'
},
// 校验用户是否已存在
{
asyncValidator: (rule, value, callback) => {
uni.$u.http.post('/xxx/xxx', {name: value}).then(res => {
// 如果验证不通过,需要在callback()抛出new Error('错误提示信息')
if(res.error) {
callback(new Error('姓名重复'));
} else {
// 如果校验通过,也要执行callback()回调
callback();
}
})
},
// 如果是异步校验,无需写message属性,错误的信息通过Error抛出即可
// message: 'xxx'
}
]
}
copy
uView提供了多种校验的错误提示方式,传递给Form
组件的errorType
参数:
message
:默认为输入框下方用文字进行提示none
:不会进行任何提示border-bottom
:配置作用域底部的下划线显示为红色,要求给form-item设置了borderBottom=true才有效toast
:以"toast"提示的方式弹出错误信息,每次只弹出最前面的那个表单域的错误信息<template>
<u--form :errorType="errorType">
......
</u--form>
</template>
<script>
export default {
data() {
return {
// 文字提示
errorType: 'message',
// 不提示
// errorType: 'none',
// 下划线提示,要求给form-item设置了borderBottom=true才有效
// errorType: 'border-bottom'
};
}
};
</script>
copy
进行了上方的配置和讲解后,进入到最后一步,执行验证:
需要通过ref
调用Form
组件的validate
方法,该方法回调函数的参数为一个布尔值,true
为校验通过,否则反之。
<template>
<view class="">
<u--form :model="form" ref="uForm">
<u-form-item label="姓名" prop="name">
<u-input v-model="form.name" />
</u-form-item>
</u--form>
<u-button @click="submit">提交</u-button>
</view>
</template>
<script>
export default {
data() {
return {
form: {
name: '',
},
rules: {
name: [
{
required: true,
message: '请输入姓名',
trigger: ['blur', 'change']
}
]
}
};
},
methods: {
submit() {
this.$refs.uForm.validate().then(res => {
uni.$u.toast('校验通过')
}).catch(errors => {
uni.$u.toast('校验失败')
})
}
},
};
</script>