此组件一般用于表单场景，可以配置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--formlabelPosition="left":model="model1":rules="rules"ref="uForm"><u-form-itemlabel="姓名"prop="userInfo.name"borderBottomref="item1"><u--inputv-model="model1.userInfo.name"border="none"></u--input></u-form-item><u-form-itemlabel="性别"prop="userInfo.sex"borderBottom@click="showSex = true; hideKeyboard()"ref="item1"><u--inputv-model="model1.userInfo.sex"disableddisabledColor="#ffffff"placeholder="请选择性别"border="none"></u--input><u-iconslot="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.namethis.$refs.uForm.validateField('userInfo.sex')},},onReady() {//如果需要兼容微信小程序，并且校验规则中含有方法等，只能通过setRules方法设置规则。this.$refs.uForm.setRules(this.rules)},
};
</script>

copy

从上面的示例我们可以看到，rules中的属性名和form的属性名是一致的，同时传递给u-form-item的prop参数绑定的也是相同的属性名，注意这里prop参数绑定的是 字符串(属性名)，而不是一个变量。

#Form-item组件说明

此组件一般需要搭配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：输入框失去焦点时触发
  • 如果同时监听两种方式，需要写成数组形式：['change', 'blur']

• type{String}
  内置校验规则，如这些规则无法满足需求，可以使用正则匹配、或者使用validator自定义方法并结合uView自带验证规则。

  • string：必须是 string 类型，默认类型
  • number：必须是 number 类型
  • boolean：必须是 boolean 类型
  • method：必须是 function 类型
  • regexp：必须是 regexp 类型，这里的正则，指的是判断字段的内容是否一个正则表达式，而不是用这个正则去匹配字段值
  • integer：必须是整数类型
  • float：必须是浮点数类型
  • array：必须是 array 类型
  • object：必须是 object 类型
  • enum：必须出现在 enmu 指定的值中
  • date：必须是 date 类型
  • url：必须是 url 类型
  • hex：必须是 16 进制类型
  • email：必须是 email 类型
  • any：任意类型

• 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自带验证规则

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和changetrigger: ['change','blur'],}]
}

copy

#综合实战

上面讲述了async-validator (opens new window)的规则和配置，以及uView内置规则的结合使用，下面我们进行一个综合 实战示例，要入对某一个字段进行如下验证(验证实现有多种方法，下方仅为引导示例，非唯一，或最优做法)：

1. 必填，同时可接受change和blur触发校验：配置required参数为true，同时配置trigger为[change, blur]
2. 必须为字母或字符串，校验前先将字段值转为字符串类型：通过pattern参数配置正则：/^[0-9a-zA-Z]*$/g，通过transform参数在校验前对字段值转换为字符串
3. 长度6-8个字符之间：通过 配置min为6，max为8
4. 需要包含字母"A"：使用uView的uni.$u.test.contains()方法，并结合validator自定义函数实现
5. 异步校验，输入完账号，输入框失去焦点时，向后端请求该账号是否已存在：通过上方的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>