前言
uni-forms 是一个用于表单管理的组件。它提供了一种简化和统一的方式来处理表单数据，包括表单验证、字段绑定和提交逻辑等。使用 uni-forms可以方便地创建各种类型的表单，支持数据双向绑定，可以与其他组件及API进行良好的集成。开发者可以提升表单处理的效率，并确保用户输入的数据符合预期要求。
提示：以下是本篇文章正文内容，下面案例可供参考
uni-rate组件具有以下特点：：
1、数据验证：内置的验证规则，可以在表单提交之前进行数据检查。
2、状态管理：自动管理表单状态（如提交状态、验证状态等）。
3、灵活的自定义：支持自定义字段和布局，适应不同的需求。
4、支持小程序和Web端：兼容多个平台，方便开发跨平台应用。
1、基本用法
uni-forms 组件通常用来做表单校验和提交。每一个 uni-forms-item 是它的一个表单域组件，用来承载表单具体内容，uni-forms-item 中可以嵌套 uni-easyinput、uni-data-checkbox 和 uni-app 内置的表单组件
<template><view class=""><uni-forms :modelValue="formData"><uni-forms-item label="姓名" name="name"><uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="年龄" name="age"><input type="text" v-model="formData.age" placeholder="请输入年龄" /></uni-forms-item><uni-forms-item required name="hobby" label="兴趣爱好"><uni-data-checkbox multiple v-model="formData.hobby" :localdata="hobby"/></uni-forms-item></uni-forms><button @click="submitForm">Submit</button></view>
</template>2、对齐方式
使用 label-position 属性可以设置所有表单域的位置，默认在左侧
<template><view class=""><uni-forms :modelValue="formData" label-position="top"><uni-forms-item label="姓名" name="name"><uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item required name="hobby" label="兴趣爱好"><uni-data-checkbox multiple v-model="formData.hobby" :localdata="hobby"/></uni-forms-item></uni-forms></view>
</template>3、表单校验
表单校验还可以直接通过 uniCloud web 控制台 快速根据 schema 自动生成表单维护界面，比如新建页面和编辑页面，自动处理校验规则。
（1）、如何使用
a、uni-forms 需要通过 rules 属性传入约定的校验规则，详细描述下文校验规则说明。
<!-- rules 内容详见下方完整示例 -->
<uni-forms ref="form" :rules="rules">...
</uni-forms>b、uni-forms 需要绑定model属性，值为表单的key\value 组成的对象。
<!-- formData、rules 内容详见下方完整示例 -->
<uni-forms ref="form" :model="formData" :rules="rules">...
</uni-forms>c、uni-forms-item 需要设置 name 属性为当前字段名，字段为 String|Array 类型。
<!-- formData、rules 内容详见下方完整示例 -->
<uni-forms :modelValue="formData" :rules="rules"><uni-forms-item label="姓名" name="name"><uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item required :name="['data','hobby']" label="兴趣爱好"><uni-data-checkbox multiple v-model="formData.data.hobby" :localdata="hobby"/></uni-forms-item>
</uni-forms>d、只要使用的组件不管内置组件还是三方组件，只需绑定 v-model，无需其他操作，即可参与校验。
e、如果使用原生 checkbox 或三方组件不支持 v-model 等，只需要给组件绑定 binddata 方法即可触发表单校验，无需绑定事件到 methods 中，见下方完整示例。
f、binddata(‘name’,$event.detail.value,‘form’)" 方法接受三个值，
- 第一个参数传入当前表单组件所在的 name，同当前父组件 uni-forms-item 绑定属性 name 的值
- 第二个参数传入需要校验的值，内置组件可以通过 $event.detail.value 获取到组件的返回值，自定义组件传入需要校验的值即可
- 第三个参数传入 uni-forms 组件绑定属性 ref 的值，通常在多表单的时候需要传入，用来区分表单，如页面中仅有一个 uni-forms 可忽略
g、如果内置 binddata 方法无法满足需求，在当前页面的 methods 中复写此方法即可，复写此方法需要调用 uni-forms 的 setValue 来触发表单校验，见下方 setValue方法说明
<template><view><uni-forms ref="form" :modelValue="formData" :rules="rules"><uni-forms-item label="姓名" name="name"><uni-easyinput type="text" v-model="formData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="邮箱" name="email"><input class="input" v-model="formData.email" type="text" placeholder="请输入邮箱" @input="binddata('email',$event.detail.value)" /></uni-forms-item></uni-forms><button @click="submit">Submit</button></view>
</template>export default {data() {return {// 表单数据formData: {name: 'LiMing',email: 'dcloud@email.com'},rules: {// 对name字段进行必填验证name: {rules: [{required: true,errorMessage: '请输入姓名',},{minLength: 3,maxLength: 5,errorMessage: '姓名长度在 {minLength} 到 {maxLength} 个字符',}]},// 对email字段进行必填验证email: {rules: [{format: 'email',errorMessage: '请输入正确的邮箱地址',}]}}}},methods: {/*** 复写 binddata 方法，如果只是为了校验，无复杂自定义操作，可忽略此方法* @param {String} name 字段名称* @param {String} value 表单域的值*/// binddata(name,value){// 通过 input 事件设置表单指定 name 的值// this.$refs.form.setValue(name, value)// },// 触发提交表单submit() {this.$refs.form.validate().then(res=>{console.log('表单数据信息：', res);}).catch(err =>{console.log('表单错误信息：', err);})}}
}（2）、校验规则说明
校验规则接受一个 Object 类型的值，通过传入不同的规则来表示每个表单域的值该如何校验
对象的 key 表示当前表单域的字段名，value 为具体的校验规则
以下为 value 所包含的内容：
rules: {// 对name字段进行必填验证name: {// name 字段的校验规则rules:[// 校验 name 不能为空{required: true,errorMessage: '请填写姓名',},// 对name字段进行长度验证{minLength: 3,maxLength: 5,errorMessage: '{label}长度在 {minLength} 到 {maxLength} 个字符',}],// 当前表单域的字段中文名，可不填写label:'姓名',validateTrigger:'submit'}
}（3）、rules 属性说明
每一个验证规则中，可以配置多个属性，下面是一些常见规则属性。实际上这里的规范，与uniCloud的DB Schema规范相同。
format属性值说明
提示：pattern属性说明
- 在小程序中，json 中不能使用正则对象，如：
/^\S+?@\S+?\.\S+?$/，使用正则对象会被微信序列化，导致正则失效。 - 所以建议统一使用字符串的方式来使用正则 ，如
'^\\S+?@\\S+?\\.\\S+?$'，需要注意\需要使用\\来转译。 - 如验证邮箱：
/^\S+?@\S+?.\S+?$/（注意不带引号）,或使用"^\S+?@\S+?\.\S+?$"（注意带引号需要使用\转义）
（4）、validateFunction 自定义校验规则使用说明
uni-forms 的 rules 基础规则有时候不能满足项目的所有使用场景，这时候可以使用 validateFunction 来自定义校验规则
validateFunction 方法返回四个参数 validateFunction:function(rule,value,data,callback){} ，当然返回参数名开发者可以自定义：
- rule : 当前校验字段在 rules 中所对应的校验规则
- value : 当前校验字段的值
- data : 所有校验字段的字段和值的对象
- callback : 校验完成时的回调，一般无需执行callback，返回true(校验通过)或者false(校验失败)即可 ，如果需要显示不同的 errMessage，如果校验不通过需要执行 callback(‘提示错误信息’)，如果校验通过，执行callback()即可
注意
- 需要注意，如果需要使用
validateFunction自定义校验规则,则不能采用uni-forms的rules属性来配置校验规则，这时候需要通过ref，在onReady生命周期调用组件的setRules方法绑定验证规则 - 无法通过
props传递变量，是因为微信小程序会过滤掉对象中的方法，导致自定义验证规则无效。 - 如果使用了
validateFunction且required为false的情况，表现为不填写内容不校验，有内容才校验，所以内容为空时validateFunction不会执行
<template><view><uni-forms ref="form" :modelValue="formData"><uni-forms-item label="兴趣爱好" required name="hobby"><uni-data-checkbox v-model="formData.hobby" multiple :localdata="hobbys" /></uni-forms-item></uni-forms><button class="button" @click="submit">校验表单</button></view>
</template>
<script>
export default {data() {return {formData:{},rules: {hobby: {rules: [{required: true,errorMessage: '请选择兴趣',},{validateFunction:function(rule,value,data,callback){if (value.length < 2) {callback('请至少勾选两个兴趣爱好')}return true}}]}}}},onReady() {// 需要在onReady中设置规则this.$refs.form.setRules(this.rules)},methods: {submit(form) {this.$refs.form.validate().then(res=>{console.log('表单数据信息：', res);}).catch(err =>{console.log('表单错误信息：', err);})}}
}
</script>（5）、validateFunction 异步校验
上面的自定义校验方式为同步校验 ，如果需要异步校验，validateFunction 需要返回一个 Promise ，校验不通过 执行 reject(new Error('错误信息')) 返回对应的错误信息，如果校验通过则直接执行 resolve() 即可，在异步校验方法中，不需要使用 callback 。
<template><view><uni-forms :modelValue="formData" ref="form"><uni-forms-item name="age" label="年龄"><uni-easyinput v-model="formData.age" type="text" placeholder="请输入年龄" /></uni-forms-item></uni-forms><button class="button" @click="submit">校验表单</button></view>
</template><script>
export default {data() {return {formData:{age:''},rules: {age: {rules: [{required: true,errorMessage: '请输入年龄',},{validateFunction: (rule, value, data, callback) => {// 异步需要返回 Promise 对象return new Promise((resolve, reject) => {setTimeout(() => {if (value > 10 ) {// 通过返回 resolveresolve()} else {// 不通过返回 reject(new Error('错误信息'))reject(new Error('年龄必须大于十岁'))}}, 2000)})}}]}}}},onReady() {// 需要在onReady中设置规则this.$refs.form.setRules(this.rules)},methods: {/*** 表单提交* @param {Object} event*/submit() {uni.showLoading()this.$refs.form.validate().then(res => {uni.hideLoading()console.log('表单数据信息：', res);}).catch(err => {uni.hideLoading()console.log('表单错误信息：', err);})}}
}
</script>API
Forms Props
Forms Events
Forms Methods
validate(keepItem:Array,callback:Function) 方法说明
validate 方法是对整个表单进行校验，方法接受两个参数
校验成功后，校验对象只保留指定了name的字段（只要 uni-forms-item 绑定了 name，哪怕不校验，也会返回），如果需要保留其他字段，则需要 keepItem 属性
<template><view><uni-forms ref="form" :modelValue="formData"><uni-forms-item name="age" label="年龄"><uni-easyinput v-model="formData.age" type="text" placeholder="请输入年龄" /></uni-forms-item><button class="button" @click="submit">校验表单</button></uni-forms></view>
</template>
<script>
export default {data() {return {formData:{age:''},rules: {// ...}}},onLoad(){this.formData.id = 'testId'},methods: {submit() {// 在 onLoad 生命周期中，formData添加了一个 id 字段 ，此时这个字段是不参数校验的，所以结果中不返回// 在 validate(['id']) 方法中，指定第一个参数 ，即可返回id字段this.$refs.form.validate(['id'],(err,formData)=>{if(!err){console.log('success',formData)}})}}
}
</script>validate 方法还可以返回一个 Promise 对象，如果使用了 callback 则Promise 返回 null，validate 方法会优先使用 callback。
callback 方法会返回两个返回值 :
- 第一个返回值为检验结果，如果校验失败，则返回失败信息，如果成功，返回 null
- 第二个返回值校验数据
// 使用 callback
// 如果不需要 keepItem 参数 ，则可以省略
this.$refs.form.validate((err,formData)=>{// 如果校验成功 ，err 返回 nullif(!err){console.log('success',formData)return}console.log('error',err)
}).then(res=>{// res 返回 null
})// 使用 Promise
// 对整个表单进行校验，返回一个 Promise
this.$refs.form.validate().then((res)=>{// 成功返回，res 为表单数据// 其他逻辑处理 // ...
}).catch((err)=>{// 表单校验验失败，err 为具体错误信息// 其他逻辑处理// ...
})
完整代码
<template><view class="container"><uni-card :is-shadow="false" is-full><text class="uni-h6">uni-forms 组件一般由输入框、选择器、单选框、多选框等控件组成，用以收集、校验、提交数据。</text></uni-card><uni-section title="基本用法" type="line"><view class="example"><!-- 基础用法，不包含校验规则 --><uni-forms ref="baseForm" :modelValue="baseFormData"><uni-forms-item label="姓名" required><uni-easyinput v-model="baseFormData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="年龄" required><uni-easyinput v-model="baseFormData.age" placeholder="请输入年龄" /></uni-forms-item><uni-forms-item label="性别" required><uni-data-checkbox v-model="baseFormData.sex" :localdata="sexs" /></uni-forms-item><uni-forms-item label="兴趣爱好" required><uni-data-checkbox v-model="baseFormData.hobby" multiple :localdata="hobbys" /></uni-forms-item><uni-forms-item label="自我介绍"><uni-easyinput type="textarea" v-model="baseFormData.introduction" placeholder="请输入自我介绍" /></uni-forms-item><uni-forms-item label="日期时间"><uni-datetime-picker type="datetime" return-type="timestamp" v-model="baseFormData.datetimesingle"/></uni-forms-item></uni-forms></view></uni-section><uni-section title="对齐方式" type="line"><view class="example"><view class="segmented-control"><uni-segmented-control :current="current" :values="items" @clickItem="onClickItem" styleType="button"></uni-segmented-control></view><!-- 展示不同的排列方式 --><uni-forms ref="baseForm" :modelValue="alignmentFormData" :label-position="alignment"><uni-forms-item label="姓名" required><uni-easyinput v-model="baseFormData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="年龄" required><uni-easyinput v-model="baseFormData.age" placeholder="请输入年龄" /></uni-forms-item></uni-forms></view></uni-section><uni-section title="表单校验" type="line"><view class="example"><!-- 基础表单校验 --><uni-forms ref="valiForm" :rules="rules" :modelValue="valiFormData"><uni-forms-item label="姓名" required name="name"><uni-easyinput v-model="valiFormData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="年龄" required name="age"><uni-easyinput v-model="valiFormData.age" placeholder="请输入年龄" /></uni-forms-item><uni-forms-item label="自我介绍" name="introduction"><uni-easyinput type="textarea" v-model="valiFormData.introduction" placeholder="请输入自我介绍" /></uni-forms-item></uni-forms><button type="primary" @click="submit('valiForm')">提交</button></view></uni-section><uni-section title="自定义校验规则" type="line"><view class="example"><!-- 自定义表单校验 --><uni-forms ref="customForm" :rules="customRules" :modelValue="customFormData"><uni-forms-item label="姓名" required name="name"><uni-easyinput v-model="customFormData.name" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item label="年龄" required name="age"><uni-easyinput v-model="customFormData.age" placeholder="请输入年龄" /></uni-forms-item><uni-forms-item label="兴趣爱好" required name="hobby"><uni-data-checkbox v-model="customFormData.hobby" multiple :localdata="hobbys" /></uni-forms-item></uni-forms><button type="primary" @click="submit('customForm')">提交</button></view></uni-section><uni-section title="动态表单" type="line"><view class="example"><!-- 动态表单校验 --><uni-forms ref="dynamicForm" :rules="dynamicRules" :modelValue="dynamicFormData"><uni-forms-item label="邮箱" required name="email"><uni-easyinput v-model="dynamicFormData.email" placeholder="请输入姓名" /></uni-forms-item><uni-forms-item v-for="(item,index) in dynamicLists" :key="item.id" :label="item.label+' '+index"required :rules="item.rules" :name="'domains[' + item.id + ']'"><view class="form-item"><uni-easyinput v-model="dynamicFormData.domains[item.id]" placeholder="请输入域名" /><button class="button" size="mini" type="default" @click="del(item.id)">删除</button></view></uni-forms-item></uni-forms><view class="button-group"><button type="primary" size="mini" @click="add">新增域名</button><button type="primary" size="mini" @click="submit('dynamicForm')">提交</button></view></view></uni-section></view>
</template><script>export default {data() {return {// 基础表单数据baseFormData: {name: '',age: '',introduction: '',sex: 2,hobby: [5],datetimesingle: 1627529992399},// 表单数据alignmentFormData: {name: '',age: '',},// 单选数据源sexs: [{text: '男',value: 0}, {text: '女',value: 1}, {text: '保密',value: 2}],// 多选数据源hobbys: [{text: '跑步',value: 0}, {text: '游泳',value: 1}, {text: '绘画',value: 2}, {text: '足球',value: 3}, {text: '篮球',value: 4}, {text: '其他',value: 5}],// 分段器数据current: 0,items: ['左对齐', '顶部对齐'],// 校验表单数据valiFormData: {name: '',age: '',introduction: '',},// 校验规则rules: {name: {rules: [{required: true,errorMessage: '姓名不能为空'}]},age: {rules: [{required: true,errorMessage: '年龄不能为空'}, {format: 'number',errorMessage: '年龄只能输入数字'}]}},// 自定义表单数据customFormData: {name: '',age: '',hobby: []},// 自定义表单校验规则customRules: {name: {rules: [{required: true,errorMessage: '姓名不能为空'}]},age: {rules: [{required: true,errorMessage: '年龄不能为空'}]},hobby: {rules: [{format: 'array'},{validateFunction: function(rule, value, data, callback) {if (value.length < 2) {callback('请至少勾选两个兴趣爱好')}return true}}]}},dynamicFormData: {email: '',domains: {}},dynamicLists: [],dynamicRules: {email: {rules: [{required: true,errorMessage: '域名不能为空'}, {format: 'email',errorMessage: '域名格式错误'}]}}}},computed: {// 处理表单排列切换alignment() {if (this.current === 0) return 'left'if (this.current === 1) return 'top'return 'left'}},onLoad() {},onReady() {// 设置自定义表单校验规则，必须在节点渲染完毕后执行this.$refs.customForm.setRules(this.customRules)},methods: {onClickItem(e) {console.log(e);this.current = e.currentIndex},add() {this.dynamicLists.push({label: '域名',rules: [{'required': true,errorMessage: '域名项必填'}],id: Date.now()})},del(id) {let index = this.dynamicLists.findIndex(v => v.id === id)this.dynamicLists.splice(index, 1)},submit(ref) {this.$refs[ref].validate().then(res => {console.log('success', res);uni.showToast({title: `校验通过`})}).catch(err => {console.log('err', err);})},}}
</script><style lang="scss">.example {padding: 15px;background-color: #fff;}.segmented-control {margin-bottom: 15px;}.button-group {margin-top: 15px;display: flex;justify-content: space-around;}.form-item {display: flex;align-items: center;}.button {display: flex;align-items: center;height: 35px;margin-left: 10px;}
</style>总而言之，uni-forms在uniapp中的作用是简化表单开发，提供常用的表单组件和相关功能，帮助开发者更快速地完成表单的处理和校验。
