Cascader 级联选择器 
概述
Cascader 级联选择器，用于一组相关联的数据集合进行选择，例如省市区等。
# 支持平台
| App-vue | App-Nvue | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节小程序 | QQ小程序 | H5 | PC | 快手小程序 | 钉钉小程序 |
|---|---|---|---|---|---|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
# 引入
以下介绍两种常用的引入方式。
第一种：在页面中引用、注册
import fuiCascader from "@/components/firstui/fui-cascader/fui-cascader.vue"
export default {
components:{
fuiCascader
}
}
1
2
3
4
5
6
2
3
4
5
6
第二种：easycom组件规范
传统vue组件，需要安装、引用、注册，三个步骤后才能使用组件。easycom将其精简为一步。
First UI easycom配置请查看 快速上手。
如果不了解easycom，可先查看 官网文档 (opens new window)。
# 代码演示
部分示例演示，完整使用请参考示例程序以及文档API。
基础使用
通过 options 属性设置选择数据，@complete 为选择完成时触发事件（无下一级表示选择完成）。
<fui-cascader :options="options" @complete="complete"></fui-cascader>
1
//data数据参考示例程序data.js
import data from './data.js'
export default
data() {
return {
options: data.options
}
},
methods: {
complete(e) {
console.log(e)
this.fui.toast(`您的选择为：${e.text.join('')}`)
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
设置默认选项
通过 options 属性设置选择数据，value 属性设置默认选项。
<fui-cascader :options="options" :value="value" @complete="complete"></fui-cascader>
1
//data数据参考示例程序data.js
import data from './data.js'
export default
data() {
return {
options: data.options，
value: ["440000", "440200", "440202", "44020203"],
}
},
methods: {
complete(e) {
console.log(e)
this.fui.toast(`您的选择为：${e.text.join('')}`)
}
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
逐级请求数据
通过 stepLoading 属性设置是否为逐级请求数据，options 属性设置第一级数据，@change 为点击item项时触发事件，返回选择数据去请求下一级数据。
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
<fui-cascader stepLoading ref="cascader" :options="layer1" @change="change" @complete="complete"></fui-cascader>
1
//data数据参考示例程序data.js
import data from './data.js'
export default
data() {
return {
layer1: data.layer_0
}
},
methods: {
change(e) {
//默认返回的为约定数据，其他属性可自行扩展
console.log(e)
//当前点击item所在层级
let layer = e.layer;
//当前点击item索引值
let index = e.index;
//value值
let val = e.value
//...
//获取下一级数据，此处为模拟，省略请求
uni.showLoading()
setTimeout(() => {
//设置请求返回数据
//当无数据时设置空数组，则会触发@complete事件，表示完成选择（或者调用end方法）
// if (layer === 5) {
// //如果层级已知，可直接判断，结束选择
// this.$refs.cascader1.end();
// return
// }
uni.hideLoading()
//请求完成后调用放法设置下一级数据，参数（data,layer）
this.$refs.cascader1.setRequestData(data[`layer_${layer+1}`], layer)
}, 300)
},
complete(e) {
console.log(e)
this.fui.toast(`您的选择为：${e.text.join('')}`)
}
}
}
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
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
逐级请求数据/设置默认选项
通过 stepLoading 属性设置是否为逐级请求数据，options 属性设置所有级默认数据，value 属性设置默认值，@change 为点击item项时触发事件，返回选择数据去请求下一级数据。
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
<fui-cascader stepLoading :options="layerData" :value="value" ref="cascader2" @change="change" @complete="complete"></fui-cascader>
1
//data数据参考示例程序data.js
import data from './data.js'
export default
data() {
return {
//分级加载设置默认数据时，需要将所有层级数据返回
//数据中不需要包含children
layerData: [data.layer_0, data.layer_1, data.layer_2, data.layer_3, data.layer_4, data.layer_5],
//默认选项value值集合
value: ["04", "0203", "0302", "0405", "0501", "0602"]
}
},
methods: {
change(e) {
//默认返回的为约定数据，其他属性可自行扩展
console.log(e)
//当前点击item所在层级
let layer = e.layer;
//当前点击item索引值
let index = e.index;
//value值
let val = e.value
//...
//获取下一级数据，此处为模拟，省略请求
uni.showLoading()
setTimeout(() => {
//设置请求返回数据
//当无数据时设置空数组，则会触发@complete事件，表示完成选择（或者调用end方法）
// if (layer === 5) {
// //如果层级已知，可直接判断，结束选择
// this.$refs.cascader2.end();
// return
// }
uni.hideLoading()
//请求完成后调用放法设置下一级数据，参数（data,layer）
this.$refs.cascader2.setRequestData(data[`layer_${layer+1}`], layer)
}, 300)
},
complete(e) {
console.log(e)
this.fui.toast(`您的选择为：${e.text.join('')}`)
}
}
}
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
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
# Slots
| 插槽名称 | 说明 |
|---|---|
| - | - |
# Props
| 属性名 | 类型 | 说明 | 默认值 | 平台差异说明 |
|---|---|---|---|---|
| options | Array | 选项数据，具体格式建下方说明 | [ ] | - |
| value | Array | 默认值，value或text集合 | [ ] | - |
| defaultKey | String | 默认值key，可选值：value、text，根据value属性决定传值 | value | - |
| stepLoading | Boolean | 是否逐级请求加载数据，为false则一次性设置所有数据 | false | - |
| showBorder | Boolean | 是否显示头部底部边框 | true | - |
| borderColor | String | 边框颜色 | #eee | - |
| headHeight | Number, String | 头部高度，单位rpx | 88 | - |
| headBackground | String | 头部背景色 | #FFFFFF | - |
| text | String | 未选则时默认显示文本 | 请选择 | - |
| size | Number, String | 头部文字大小，单位rpx | 28 | - |
| color | String | 头部文字颜色 | #181818 | - |
| activeColor | String | 高亮颜色,包括头部当前选项卡文本，底部线条，对号✓高亮色 | #465CFF | 非Nvue端默认为空，可使用css变量（--fui-color-primary）来改变颜色 |
| showLine | Boolean | 选项卡文本是否显示底部线条 | true | - |
| height | Number, String | 选择（内容）区域高度，单位rpx | 600 | - |
| background | String | 选择（内容）区域背景颜色 | #FFFFFF | - |
| checkMarkColor | String | 对号颜色，为空则默认使用activeColor | - | - |
| imgWidth | Number, String | 选择内容item项图片宽度，单位rpx | 48 | - |
| imgHeight | Number, String | 选择内容item项图片高度，单位rpx | 48 | - |
| radius | Number, String | 选择内容item项图片圆角值，单位rpx | 0 | - |
| textSize | Number, String | 选择内容item项文本字体大小，单位rpx | 26 | - |
| textColor | String | 选择内容item项文本字体颜色 | #181818 | - |
| textActiveColor | String | 选择内容item项文本选中时字体颜色 | #181818 | - |
/*
options数据格式介绍，有三种数据格式
通过stepLoading属性（是否发起请求返回下一级选择数据）传入不同格式数据
*/
//=====================================================
//stepLoading 为 false 时，则一次性传入所有数据
//以下text、value、src、children为约定属性，其他属性可自行添加，如id等
//按照以下数据格式组装数据，理论可支持n级数据
options:[{
//text值，显示文本
text: '广东省',
//value值
value: '440000',
//图标图片src地址，可选
src:'',
//子级数据
children: [{
text: '广州市',
value: '440100',
src:'',
//子级数据
children:[]
}, {
text: '韶关市',
value: '440200',
src:'',
//子级数据
children:[]
}]
}]
//=====================================================
//stepLoading 为 true 时，分为以下情况
//不设置默认值时，options仅为第一级数据，无需children项
options:[{
//text值，显示文本
text: '北京市',
//value值
value: '100000',
//图标图片src地址，可选
src:''
}, {
//text值，显示文本
text: '广东省',
//value值
value: '440000',
//图标图片src地址，可选
src:''
}]
//设置默认值时，options为所有级数据集合，无需children项
//如设置默认值value:["440000","440100","440101"]，则设置options如下：
options:[
//第一级数据
[{
//text值，显示文本
text: '广东省',
//value值
value: '440000',
//图标图片src地址，可选
src:''
}],
//第二级数据
[{
text: '广州市',
value: '440100'
},{
text: '韶关市',
value: '440200'
}],
//第三级数据
[{
text: '荔湾区',
value: '440101'
},{
text: '越秀区',
value: '440102'
}]
]
//=====================================================
//value默认值说明：value集合或text集合
//设置为value集合时属性defaultKey值需设置为'value'
//设置为text集合时属性defaultKey值需设置为'text'
["440000","440100","440101"]
或
["广东省","广州市","荔湾区"]
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
# Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| @change | 点击选择数据item项时触发 | { layer : 点击的item项所在层级 index : 点击的item索引值 ...item : item项数据 } |
| @complete | 完成选择时触发 | { result : 结果数据 value : value值集合 text : text值集合 src : src值集合 } |
# Methods
通过 ref 属性来注册组件引用信息。注册完成后，我们可以通过this.$refs.XXX访问到对应的组件实例，并调用上面的实例方法。
| 方法名 | 说明 | 传入参数 | 返回参数 |
|---|---|---|---|
| reset | 重置选择数据 | - | - |
| setRequestData | 设置请求返回数据，stepLoading 为 true 时使用，设置空数组则与end方法效果一致，结束选择 | setRequestData(data, layer)：data数据和@change事件返回的layer值 | - |
| end | 选择结束，stepLoading 为 true 时使用，调用该方法则触发@complete事件 | end(layer)：@change事件返回的layer值 | - |
示例预览
# 示例代码地址
VIP内容代码请查看订单页下载的组件库示例源码。# 特别说明
该组件为付费组件，UNI-APP版VIP用户可免费使用 。