前言
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 ) {
// 通过返回 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
属性
<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 返回 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 为具体错误信息
// 其他逻辑处理
// ...
})
完整代码
<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中的作用是简化表单开发,提供常用的表单组件和相关功能,帮助开发者更快速地完成表单的处理和校验。