前言
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 内置的表单组件
html
<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 属性可以设置所有表单域的位置，默认在左侧
html
<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 属性传入约定的校验规则，详细描述下文校验规则说明。
html
<!-- rules 内容详见下方完整示例 -->
<uni-forms ref="form" :rules="rules">
...
</uni-forms>b、uni-forms 需要绑定model属性，值为表单的key\value 组成的对象。
html
<!-- formData、rules 内容详见下方完整示例 -->
<uni-forms ref="form" :model="formData" :rules="rules">
...
</uni-forms>c、uni-forms-item 需要设置 name 属性为当前字段名，字段为 String|Array 类型。
html
<!-- 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方法说明
html
<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>
javascript
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 所包含的内容：
javascript
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不会执行
html
<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 。
html
<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 ) {
// 通过返回 resolve
resolve()
} 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 属性
html
<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
- 第二个返回值校验数据
javascript
// 使用 callback
// 如果不需要 keepItem 参数 ，则可以省略
this.$refs.form.validate((err,formData)=>{
// 如果校验成功 ，err 返回 null
if(!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 为具体错误信息
// 其他逻辑处理
// ...
})
完整代码
html
<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>
javascript
<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>
css
<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中的作用是简化表单开发，提供常用的表单组件和相关功能，帮助开发者更快速地完成表单的处理和校验。