FormItem 表单项 
V1.7.0+
概述
FormItem 表单项，主要用于表单组件相关布局使用。
# 支持平台
| App-vue | App-Nvue | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 | H5 | PC | 快手小程序 | 钉钉小程序 |
|---|---|---|---|---|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
# 引入
以下介绍两种常用的引入方式。
第一种：在页面中引用、注册
import fuiFormItem from "@/components/firstui/fui-form-item/fui-form-item.vue"
export default {
components:{
fuiFormItem
}
}
1
2
3
4
5
6
2
3
4
5
6
第二种：easycom组件规范
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。
First UI easycom配置请查看 快速上手。
如果不了解easycom，可先查看 官网文档 (opens new window)。
# 代码演示
部分示例演示，完整使用请参考示例程序以及文档API。
基础使用
通过 label 属性设置标签文本。
<fui-form-item label="活动名称">
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入活动名称"></fui-input>
</fui-form-item>
<fui-form-item label="手机号码">
<input class="fui-page__input" placeholder="请输入手机号码" placeholder-style="color:#ccc;" />
</fui-form-item>
<fui-form-item label="即时配送">
<fui-switch :scaleRatio="0.9"></fui-switch>
</fui-form-item>
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
必填星号
通过 label 属性设置标签文本，asterisk 属性设置是否显示星号。
<fui-form-item label="姓名" asterisk>
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入姓名"></fui-input>
</fui-form-item>
<fui-form-item label="手机号码" asterisk>
<input class="fui-page__input" placeholder="请输入手机号码" placeholder-style="color:#ccc;" />
</fui-form-item>
1
2
3
4
5
6
2
3
4
5
6
选择、显示箭头
通过 label 属性设置标签文本，arrow 属性设置是否显示箭头，highlight 属性设置是否需要点击效果。
<fui-form-item label="活动时间" asterisk arrow highlight>
<fui-input :borderBottom="false" :padding="[0]" placeholder="请选择时间" disabled
backgroundColor="transparent"></fui-input>
</fui-form-item>
<fui-form-item label="地区" arrow highlight>
<input class="fui-page__input" placeholder="请选择地区" placeholder-style="color:#ccc;" disabled />
</fui-form-item>
1
2
3
4
5
6
7
2
3
4
5
6
7
表单校验，统一设置校验规则（V2.2.0+）
校验规则由校验方法传入
<template>
<view class="fui-wrap">
<fui-form ref="form" top="0" :model="formData" :show="false">
<fui-form-item label="姓名" asterisk prop="name">
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入姓名"
v-model="formData.name"></fui-input>
</fui-form-item>
<fui-form-item label="手机号码" asterisk prop="mobile">
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入手机号码" v-model="formData.mobile"></fui-input>
</fui-form-item>
<view class="fui-btn__box">
<fui-button text="Submit" bold @click="submit"></fui-button>
</view>
</fui-form>
</view>
</template>
<script>
/*
结合表单校验显示错误信息需要注意：
1、fui-form-item 组件 必须设置prop属性
2、fui-form 组件必须设置 model属性，且show属性必须设为false
3、form 组件validator方法第三个参数必须传true
*/
const rules = [{
name: "name",
rule: ["required", "isChinese", "minLength:2", "maxLength:6"],
msg: ["请输入姓名", "姓名必须全部为中文", "姓名必须2个或以上字符", "姓名不能超过6个字符"]
}, {
name: "mobile",
rule: ["required", "isMobile"],
msg: ["请输入手机号", "请输入正确的手机号"]
}];
export default {
data() {
return {
formData: {
name: '',
mobile: ''
}
}
},
onReady() {
//开启实时校验【当前item项内容改变即校验】
// this.$refs.form && this.$refs.form.switchRealTimeValidator(true, rules)
},
methods: {
submit() {
console.log(this.formData)
//注意：validator方法第三个参数必须传true
this.$refs.form.validator(this.formData, rules, true).then(res => {
console.log(res)
if (res.isPassed) {
console.log('校验通过！')
} else {
console.log('向上滑动页面查看错误提示！')
}
}).catch(err => {
console.log(err)
})
}
}
}
</script>
<style>
.fui-wrap {
padding-bottom: 96rpx;
}
.fui-btn__box {
width: 100%;
padding: 64rpx 32rpx 0;
box-sizing: border-box;
}
</style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
表单校验，单独设置校验规则（V2.2.0+）
校验规则由FormItem组件传入
<template>
<view class="fui-wrap">
<fui-form ref="form" top="0" :model="formData" :show="false">
<fui-form-item label="姓名" asterisk :rules="rules[0]" prop="name">
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入姓名"
v-model="formData.name"></fui-input>
</fui-form-item>
<fui-form-item label="手机号码" asterisk :rules="rules[1]" prop="mobile">
<fui-input :borderBottom="false" :padding="[0]" placeholder="请输入手机号码" v-model="formData.mobile"></fui-input>
</fui-form-item>
<view class="fui-btn__box">
<fui-button text="Submit" bold @click="submit"></fui-button>
</view>
</fui-form>
</view>
</template>
<script>
const rules = [{
name: "name",
rule: ["required", "isChinese", "minLength:2", "maxLength:6"],
msg: ["请输入姓名", "姓名必须全部为中文", "姓名必须2个或以上字符", "姓名不能超过6个字符"]
}, {
name: "mobile",
rule: ["required", "isMobile"],
msg: ["请输入手机号", "请输入正确的手机号"]
}];
export default {
data() {
return {
rules,
formData: {
name: '',
mobile: ''
}
}
},
onReady() {
//开启实时校验【当前item项内容改变即校验】
// this.$refs.form && this.$refs.form.switchRealTimeValidator(true, rules)
},
methods: {
submit() {
console.log(this.formData)
//注意：validator方法第三个参数必须传true
this.$refs.form.validator(null, null, true).then(res => {
console.log(res)
if (res.isPassed) {
console.log('校验通过！')
} else {
console.log('向上滑动页面查看错误提示！')
}
}).catch(err => {
console.log(err)
})
}
}
}
</script>
<style>
.fui-wrap {
padding-bottom: 96rpx;
}
.fui-btn__box {
width: 100%;
padding: 64rpx 32rpx 0;
box-sizing: border-box;
}
</style>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
# Slots
| 插槽名称 | 说明 |
|---|---|
| default | 组件内部内容，由表单组件组成 |
| right | 组件右侧显示内容 |
| vertical V2.1.0+ | 纵向排列时自定义内容 |
# Props
| 属性名 | 类型 | 说明 | 默认值 | 平台差异说明 |
|---|---|---|---|---|
| padding | Array | padding值（上，右，下，左），同css顺序,如：['32rpx','32rpx'] | ['30rpx', '32rpx'] | - |
| marginTop | Number, String | margin-top值，单位rpx | 0 | - |
| marginBottom | Number, String | margin-bottom值，单位rpx | 0 | - |
| label | String | 标签文本 | - | - |
| labelSize | Number, String | 标题字体大小，单位rpx，默认使用全局设置值 | 0 | - |
| labelColor | String | 标题字体颜色，默认使用Form组件props属性值 | - | - |
| labelWidth | Number, String | label宽度，单位rpx，默认使用全局设置值 | 0 | - |
| labelRight | Number, String | label与右侧内容距离，单位rpx，默认使用全局设置值 | 0 | - |
| labelAlign V1.9.0+ | String | label对齐方式，可选值：left，right | left | - |
| labelWeight V1.9.8+ | Number,String | label字重，同font-weight，默认使用全局设置值 | 0 | - |
| asterisk | Boolean | 是否显示必填的红色星号 | false | - |
| asteriskColor | String | 星号颜色，默认使用Form组件props属性值 | - | - |
| asteriskPosition V1.9.0+ | String | 星号位置，可选值：left，right | left | - |
| background | String | item项背景颜色 | #fff | - |
| highlight | Boolean | 是否有点击效果 | false | - |
| arrow | Boolean | 是否需要箭头（选择效果） | false | - |
| arrowColor | String | 箭头颜色 | #B2B2B2 | - |
| bottomBorder | Boolean | 是否需要底部边框 | true | - |
| borderColor | String | 底部边框颜色 | #EEEEEE | - |
| left | Number, String | 底部边框left值，单位rpx | 32 | - |
| right | Number, String | 底部边框right值，单位rpx | 0 | - |
| radius | String | item项圆角值 | 0rpx | - |
| param | Number, String | 自定义参数，随点击事件回传 | 0 | - |
| prop V2.1.0+ | String | 表单域 model 字段，在使用校验时该属性是必填的 | - | - |
| errorPosition V2.1.0+ | Number, String | 组件错误提示定位方式方式：1-absolute 2-relative，默认使用Form组件中属性值 | 1 | - |
| errorAlign V2.1.0+ | String | 组件错误提示显示对齐方式，可选值：left、center、right，默认使用Form组件中属性值 | center | - |
| rules V2.2.0+ | Object | 表单验证规则，部分平台不支持嵌套传入函数，请使用setRules 或 setRulesMerge 方法传入 | {} | - |
/*
rules 表单验证规则（V2.2.0+） 数据格式说明，可参考Form组件内单项规则设置：
=======================
rules：Object 校验规则数据，格式 {name:value,rule:[],msg:[],validator:[]}
-------------------
name：String，元素的名称，与prop属性值一致
rule：Array<String> ，内置的校验方法名称集合，详细见下方说明
msg：Array<String>，对应rule规则方法的错误提示信息
validator：Array<Object>，自定义校验方法集合，格式 [{msg:'出错后提示信息',method:Function 校验法法}]
-----------
method：校验方法约定必须返回 true 或 false 作为校验结果
=======================
*/
//可设置格式如下：
{
name: "mobile",
rule: ["required", "isMobile"],
msg: ["请输入手机号", "请输入正确的手机号"]
}
//或自定义校验规则（如果自定义规则请使用方法传入），格式如下：
{
name: "agree",
validator: [{
msg: "请勾选并同意《FirstUI 相关条款》",
method: checkAgree
}]
}
// 注：rule 和 validator 可共存，同时设置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
TIP V2.1.0+
当结合Form组件进行表单校验，显示错误信息时需要注意：
fui-form-item组件 必须设置prop属性fui-form组件必须设置model属性，且show属性必须设为falsefui-form组件validator方法第三个参数必须传true- 当 属性
errorPosition值设置为1时，注意控制提示内容文本长度，建议不要超过一行，开发时请自行注意，若提示内容过长请将属性值设置为2
# Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| @click | item项点击时触发 | { param : 自定义参数 } |
# Methods
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
| 方法名 | 说明 | 传入参数 | 返回参数 |
|---|---|---|---|
| setRules V2.2.0+ | 设置校验规则，格式如上方属性rules | rules : Object 校验规则数据 | - |
| setRulesMerge V2.2.0+ | 设置校验规则，并通知Form组件合并或替换该项对应的rule | rules : Object 校验规则数据 | - |
| validator V2.2.0+ | 校验方法，仅结合Form组件使用时有效 | value : any 字段值 | { isPassed : 是否验证通过 errorMsg : 错误消息 } |
| clearValidate V2.2.0+ | 清除校验错误信息 | - | - |
//方法及参数详细说明
/**
* 设置校验规则（V2.2.0+）
* @param {Object} rules 表单验证规则，由于属性传入部分平台不支持嵌套自定义函数，当不支持时请使用方法传入
*/
setRules(rules)
/**
* 设置校验规则，并通知Form组件合并或替换该项对应的rule（V2.2.0+）
* @param {Object} rules 表单验证规则，由于属性传入部分平台不支持嵌套自定义函数，当不支持时请使用方法传入
* 如果Form组件校验 rules 传null时，会自动查找FormItem组件内rules，如果传入了rules值时，后续动态新增属性可使用此方法并入rules数据
*/
setRulesMerge(rules)
/**
* 验证方法
* @param {any} value 字段值，不传则使用Form组件model中值
*/
validator(value)
/**
* 清除当前项校验错误信息（V2.2.0+）
*/
clearValidate()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
示例预览
# 示例代码地址
VIP内容代码请查看订单页下载的组件库示例源码。# 特别说明
该组件为付费组件，UNI-APP版VIP用户可免费使用 。← Form 表单校验 Select 选择器 →