《uni-app》表单组件-Picker组件

本文分享的picker组件为uni-app的内置组件picker，非扩展组件，两者在用法上其实大同小异，只是扩展组件的属性以及事件更多…没有本质上的区别～

一. 简介

picker，选择器组件，该组件为一个复合组件，它内置了 五种选择器，分别为：普通选择器，多列选择器，时间选择器，日期选择器，省市区选择器；
选择器在表单组件中同样属于使用频率非常高的一种，常见的业务场景包括，外卖、快递时的地区选择，注册时的日期选择，时间选择等等；

二. mode属性

mode属性，用于控制picker组件处于哪一种形态，从简介中知道，uni-app官网在picker组件中一共内置了 五种形态的选择器，这五种选择器实际上会分别 对应五种mode值，具体如下：

具体代码示例如下：

<picker :range="array" mode="selector">普通选择器picker>


<picker mode="time">时间选择器picker>


<picker mode="multiSelector">多列选择器picker>


<picker mode="date">日期选择器picker>


<picker mode="region">省市区选择器picker>
1
2
3
4
5
6
7
8
9
10
11
12
13
14

三. 普通选择器（selector）

3.1 基础用法

普通选择器 的使用需将 mode属性 设置为 selector，或者 不使用mode属性，示例代码如下：

<picker :range="array">普通选择器picker>


<picker :range="array" mode="selector">普通选择器picker>

<script>
export default {
	data() {
		return {
			array: ['中国', '美国', '巴西', '日本']
		};
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

点击 “普通选择器” 文字时，将从底部弹起的滚动选择器，选择器内容分别为：中国，美国，巴西，日本，其表现形态 效果图 如下：

3.2 range属性

range属性，用于 设置选择器的选项也就是数据源，它可以是一个 数组 或者 是一个 key/value组成的object，示例代码如下：

<picker :range="array" mode="selector">普通选择器picker>

<script>
export default {
	data() {
		return {
			array: ['中国', '美国']
		};
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12

或者range的值为对象时

<picker :range="array" mode="selector">普通选择器picker>

<script>
export default {
	data() {
		return {
			array: {
				china: '中国',
				usa: '美国'
			}
		};
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

这两者的 效果完全一致，具体表现形态 效果图 如下：

3.3 range-key属性

range-key属性，用于当 range属性的值的类型为Array[Object]时，指定列表显示字段所用，举个例子，代码如下：

<picker :range="array" range-key="name">普通选择器picker>
<script>
export default {
	data() {
		return {
			array: [
				{
					id: 'cn',
					name: '中国'
				},
				{
					id: 'usa',
					name: '美国'
				},
				{
					id: 'brazil',
					name: '巴西'
				},
				{
					id: 'japan',
					name: '日本'
				}
			]
		};
	}
};
script>
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

上例array对应的这种数据格式其实非常常见，从后台返回的数据绝大多数其实是这种格式的数据类型，但是picker组件展示的内容为一个 string[]数组，因此如果要转成 string[] 格式，那么需要对array做数据转化，为了解决这个问题，因此便有了 range-key，range-key用于指定对象中哪个字段需要展示，上例中为name对应的值需要展示，其表现形态 效果图 如下：

如果将 range-key 指向 id，那么效果图如下
说白了，就是哪个字段对应的值需要展示在选项上；

3.4 value属性

value属性，用于指定当前列表中哪个项处于选中状态，属性说明如下：

比如，上面例子中需要指定 巴西 为picker组件打开时默认的选中项，那么可以将value值设置成 2（注意，value值必须是数字，是当前需要被选中项在数组中的下标值）

<picker :range="array" range-key="name" :value="2">普通选择器picker>
1
2

其表现形态 效果图 如下：

3.5 selector-type属性

selector-type，用于设置picker组件的列表展示形式，它有3个值，说明如下：

简单的说就是这个值是 用来手动设置弹窗形态 的，比如之前的例子都是 将从底部弹起的滚动选择器 这种形态称之为picker，移动端基本都是这种形态，但是我们知道uni-app本身是一个跨平台的解决方案，当app处于大屏，或者干脆就是PC端的时候，并不合适出现滚动选择器，因此便有了 select 这个选项，示例代码如下：

<picker :range="array" range-key="name" :value="2" selector-type="select">普通选择器picker>
1
2

在PC浏览器上，其表现形态 效果图 如下：

很明显，此时已变成了一个菜单～

3.6 change事件

change事件，点击 完成切换value值 时触发，说明如下：

以上方代码为例，默认国家名称显示 中国 ，打开选择器，选中其他国家后，国家名称改变为选中国时会触发这个事件，示例代码如下：

<picker 
  :range="array" 
  :value="2" 
  range-key="name" 
  selector-type="select" 
  @change="changePcikerVal">
  {{ array[index].name }}
picker>

<script>
export default {
	data() {
		return {
			index: 0,
			array: [
				{
					id: 'cn',
					name: '中国'
				},
				{
					id: 'usa',
					name: '美国'
				},
				{
					id: 'brazil',
					name: '巴西'
				},
				{
					id: 'japan',
					name: '日本'
				}
			]
		};
	},
	methods: {
		changePcikerVal(e) {
			this.index = e.detail.value;
		}
	}
};
script>
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

其表现形态 效果图 如下：

3.7 cancel事件

cancel事件，点击列表中的 取消按钮 时触发，说明如下：

以上方选项为例，点击 取消按钮 时，触发alert弹窗，示例代码如下：

<picker 
  :range="array" 
  :value="2" 
  range-key="name" 
  selector-type="select" 
  @cancel="handleCancel">{{ array[index].name }}picker>
1
2
3
4
5
6
7

其表现形态 效果图 如下：

四. 多列选择器

4.1 基础用法

多列选择器 的使用需将 mode属性 设置为 multiSelector，示例代码如下：

<picker :range="array" mode="multiSelector">多列选择器picker>

<script>
export default {
	data() {
		return {
			array: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']]
		};
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12

点击 “多列选择器” 文字时，将从底部弹起的滚动选择器，选择器内容为一个 二维数组，其表现形态 效果图 如下：

4.2 range属性

和 普通选择器 不同的是，多列选择器的range接收一个二维数组作为其参数实现多列效果，具体说明如下：

以基础用法中的数据为例，数据array为：

array: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']]
1

通过说明我们知道，第一维数组中的 每一项代表一列，第二维数组代表这一列有多少项，因此这组数据会组成一个3列的多列选择器，其表现形态 效果图 如下：

4.3 相同属性说明

多列选择器 形态上与普通选择器非常接近，因此 很多属性与普通选择器的用法保持一致，具体如下：

这几个的用法与普通选择器的用法几乎一摸一样 不再过多介绍，演示代码如下：

<picker 
:range="array" 
mode="multiSelector" 
:value="index" 
range-key="name" 
selector-type="select" 
@cancel="handleCancel">{{ array[0][1] }}picker>

<script>
export default {
	data() {
		return {
			index: [1, 2, 1],
			array: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']]
		};
	},
	methods: {
		handleCancel() {
			alert('取消');
		}
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

4.4 columnchange事件

columnchange事件，这是多列选择器的专属事件，作用时当多列选择器中的某一列的值改变时触发，说明如下：

以上方代码为例，默认第一列默认时脊柱动物，当切换这一列时，即会触发 columnchange事件

<template>
	<view class="demo-container">
		
    <picker :range="array" mode="multiSelector" :value="index" range-key="name" selector-type="select" @cancel="handleCancel" @columnchange="columnchange">
      {{ array[0][1] }}
    picker>
	view>
template>

<script>
export default {
	data() {
		return {
			index: [1, 2, 1],
			array: [['无脊柱动物', '脊柱动物'], ['扁性动物', '线形动物', '环节动物', '软体动物', '节肢动物'], ['猪肉绦虫', '吸血虫']]
		};
	},
	methods: {
		columnchange(event) {
			const { column, value } = event.detail;
			alert(column);
		}
	}
};
script>
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

当切换第一列时，会alert当前切换的是哪一列，其表现形态 效果图 如下：

4.5 平台差异

支付宝小程序 picker 组件不支持多列选择，可以使用 picker-view 组件替代。

五. 时间选择器

5.1 基础用法

时间选择器 的使用需将 mode属性 设置为 time，示例代码如下：

<picker mode="time">时间选择器picker>
1
2

点击 “时间选择器” 文字时，将从底部弹起的滚动选择器，选择器内容为一个 由小时、分钟组成的两列选择器，其表现形态 效果图 如下：

5.2 value属性

value属性，用于 指定默认的选中时间，属性说明如下：

比如，需要将默认的选中时间改为中午的12点整，那么value值可以设定为 “12:00”

<picker mode="time" value="12:00">{{ time || '时间选择器' }}picker>
1
2

其表现形态 效果图 如下：

5.2 start属性与end属性

start属性 与 end属性，用于指定时间的选择范围，当设定了这两个属性后选择的时间如果超出该范围，那么会立刻滚回到设定的时间内，说明如下：

示例代码 如下：

!-- 时间选择器 -->
<picker 
  mode="time" 
  value="12:00" 
  start="11:00" 
  end="12:00">
  {{ time || '时间选择器' }}
picker>
1
2
3
4
5
6
7
8

其表现形态 效果图 如下：

5.4 相同属性说明

多列选择器 形态上与普通选择器非常接近，因此 很多属性与普通选择器的用法保持一致，具体如下：

这几个的用法与普通选择器的用法几乎一摸一样，演示代码如下：

<picker 
  mode="time" 
  value="12:00" 
  start="11:00" 
  end="12:00" 
  @change="changeTime">{{ time || '时间选择器' }}picker>

<script>
export default {
	data() {
		return {
			time: ''
		};
	},
	methods: {
		changeTime(event) {
			const { value } = event.detail;
			this.time = value;
		}
	}
};
script>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

其表现形态 效果图 如下：

5.5 平台差异

时间选择在App端调用的是os的原生时间选择控件，在不同平台有不同的ui表现。

六. 日期选择器

6.1 基础用法

日期选择器 的使用需将 mode属性 设置为 date，示例代码如下：

<picker mode="date">日期选择器picker>
1
2

点击 “日期选择器” 文字时，将从底部弹起的滚动选择器，选择器内容为一个 由年、月、日组成的三列选择器，其表现形态 效果图 如下：

6.2 value属性，start属性与end属性

与 time类型的时间选择器一样，日期选择器也具有 value属性，start属性，end属性，并且用法也几乎一致，最大区别在于格式不一致，日期选择器的格式为：YYYY-MM-DD，具体说明如下：

示例代码如下：

<picker 
  mode="date" 
  value="2022-09-05" 
  start="2022-09-04" 
  end="2022-09-10">{{ time || '日期选择器' }}picker>
1
2
3
4
5
6

其表现形态 效果图 如下：

6.3 fields属性

fields属性，用于设置日期选择器的颗粒度，也就是选择器的选项是到日，还是月，又或者是年，属性说明如下：

示例代码如下：

<picker fields="month">{{ time || '日期选择器' }}picker>
1
2

其表现形态 效果图 如下：

同理，如果需要将其设置成只选年，那么 fields属性 设置成 year 即可；

6.4 相同属性说明

日期选择器 也存在 change事件，cancel事件，disabled属性，并且 用法保持一致，具体如下：

由于用法完全一致，因此不过多介绍了，具体示例与使用参照普通选择器，多列选择器的用啊。

6.5 平台差异

日期选择默认在App端和H5端（PC版Chrome以及PC版FireFox）调用的是os的原生日期选择控件，在不同平台有不同的ui表现，当配置fields参数后使用统一的展示方式。

七. 省市区选择器

7.1 基础用法

省市区选择器 的使用需将 mode属性 设置为 region，示例代码如下：

<picker mode="date">日期选择器picker>
1
2

点击 “省市区选择器” 文字时，将从底部弹起的滚动选择器，选择器内容为一个 由省、市、区组成的三列选择器，注意的是，由于省、市、区的数据庞大，uni-app并没有直接维护在组件里，而是直接借用小程序内部的数据，因此如果是微信小程序端，需要在编译后进入微信开发者工具查看，其表现形态 效果图 如下：

如果想要在h5端显示，可以借助第三方插件，直接打开uni-app的插件商城搜索：“城市选择” 即可；

7.2 相同属性说明

省市区选择器的用法与其他选择器的用法基本相同，属性如下：

示例代码如下：

<template>
	<view class="demo-container">
		
		<view class="demo-group">
			<h4>省市区选择器h4>
			
			<picker mode="region" @change="change">{{ add[0] || '省市区选择器' }}picker>
		view>
	view>
template>

<script>
export default {
	data() {
		return {
			add: []
		};
	},
	methods: {
		change(event) {
			const { value } = event.detail;
			this.add = value;
		}
	}
};
script>
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

其表现形态 效果图 如下：

八. 小结

本文主要分享了uni-app中内置组件picker的一些用法，picker组件包含了五种形态的选择器，分别是：普通选择器，多列选择器，时间选择器，日期选择器，省市区选择器；之后，我们详细介绍了这五种选择器的基础用法以及其对应的各个属性，我们发现，其实这些选择器的用法基本都大同小异，无非就是数据源是内置的还是外部传入的，事件也几乎相同，我们只需要熟悉其中一种，那么剩下的选择器也就基本能掌握了～