Skip to content

U
uni-app

DCloud / uni-app
4 个月 前同步成功

通知 731
Star 38707
Fork 3642
U
uni-app
切换分支/标签
查找文件 普通视图历史永久链接Permalink
picker.md 8.7 KB
Newer Older
M
feat: docs  
mehaotian 已提交
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 
#### picker

从底部弹起的滚动选择器，现支持五种选择器，通过mode来区分，分别是普通选择器，多列选择器，时间选择器，日期选择器，省市区选择器，默认是普通选择器。

**普通选择器**

``mode = selector``

**属性说明**

|属性名|类型|默认值|说明|
|:-|:-|:-|:-|
|range|Array / Array＜Object＞|[]|mode为 selector 或 multiSelector 时，range 有效|
|range-key|String||当 range 是一个 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容|
|value|Number|0|value 的值表示选择了 range 中的第几个（下标从 0 开始）|
|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}|
|disabled|Boolean|false|是否禁用|
|@cancel|EventHandle||取消选择或点遮罩层收起 picker 时触发|


**多列选择器**

``mode = multiSelector``

**平台差异说明**

|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|
W
Update picker.md  
wanganxp 已提交
29 
|vue支持，nvue不支持|√|√|x|√|√|
M
feat: docs  
mehaotian 已提交
30 31 32 33 34 35 36 37 38 39 40 41 42 43 


**属性说明**

|属性名|类型|默认值|说明|
|:-|:-|:-|:-|
|range|二维 Array / 二维 Array＜Object＞|[]|mode为 selector 或 multiSelector 时，range 有效。二维数组，长度表示多少列，数组的每项表示每列的数据，如[["a","b"], ["c","d"]]|
|range-key|String||当 range 是一个二维 Array＜Object＞ 时，通过 range-key 来指定 Object 中 key 的值作为选择器显示内容|
|value|Array|[]|value 每一项的值表示选择了 range 对应项中的第几个（下标从 0 开始）|
|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}|
|@columnchange|EventHandle||某一列的值改变时触发 columnchange 事件，event.detail = {column: column, value: value}，column 的值表示改变了第几列（下标从0开始），value 的值表示变更值的下标|
|@cancel|EventHandle||取消选择时触发|
|disabled|Boolean|false|是否禁用|
W
Update picker.md  
wanganxp 已提交
44 
**bug & tips**
M
feat: docs  
mehaotian 已提交
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 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 
- 由于 JavaScript 的限制 vue 不能观测如下方式设置 value：``this.value[0] = 0`` （[vue 注意事项](https://cn.vuejs.org/v2/guide/list.html#注意事项)），解决方式参考：[hello-uniapp 示例](https://github.com/dcloudio/hello-uniapp/commit/59264474172a591c865431d02a2a1e3583978827)
- 微信开发工具的pc模拟器有可能出现拖动数据错乱，使用真机正常

**时间选择器**

``mode = time``

**平台差异说明**

|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|x|√|√|

**属性说明**

|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|value|String||表示选中的时间，格式为"hh:mm"||
|start|String||表示有效时间范围的开始，字符串格式为"hh:mm"|5+App 不支持|
|end|String||表示有效时间范围的结束，字符串格式为"hh:mm"|5+App 不支持|
|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}||
|@cancel|EventHandle||取消选择时触发||
|disabled|Boolean|false|是否禁用| |

**日期选择器**

``mode = date``

**平台差异说明**

|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√|√|x|√|√|

**属性说明**

|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|value|String|0|表示选中的日期，格式为"YYYY-MM-DD"||
|start|String||表示有效日期范围的开始，字符串格式为"YYYY-MM-DD"||
|end|String||表示有效日期范围的结束，字符串格式为"YYYY-MM-DD"||
|fields|String|day|有效值 year,month,day，表示选择器的粒度|H5、微信小程序、百度小程序、头条小程序|
|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}||
|@cancel|EventHandle||取消选择时触发||
|disabled|Boolean|false|是否禁用| |

**fields 有效值**

|值|说明|
|:-|:-|
|year|选择器粒度为年|
|month|选择器粒度为月份|
|day|选择器粒度为天|

**省市区选择器**

``mode = region``

**平台差异说明**

|5+App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|
|x|x|√|x|√|√|

- 因省市区选择器包含大量数据，占用体积，且很多城市数据有自维护需求，所以在App和H5平台没有内置。有两种方案解决：
	1. 使用mpvue-picker代替，全端通用，自定义性更强，参考： Hello uni-app的模板-多列选择picker，或[插件市场](https://ext.dcloud.net.cn/plugin?id=115)。手机预览网址：[https://uniapp.dcloud.io/h5/pages/template/mpvue-picker/mpvue-picker](https://uniapp.dcloud.io/h5/pages/template/mpvue-picker/mpvue-picker)
	2. 在H5和App平台使用多列选择器，自行填充城市数据（上述mpvue-picker或hello uni-app自带城市数据city.data.js）

|属性名|类型|默认值|说明|
|:-|:-|:-|:-|
|value|Array|[]|表示选中的省市区，默认选中每一列的第一个值|
|custom-item|String||可为每一列的顶部添加一个自定义的项|
|@change|EventHandle||value 改变时触发 change 事件，event.detail = {value: value}|
|@cancel|EventHandle||取消选择时触发|
|disabled|Boolean|false|是否禁用|

**示例**
 
```html
<template>
	<view>
		<view class="uni-title uni-common-pl">地区选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker @change="bindPickerChange" :value="index" :range="array">
						<view class="uni-input">{{array[index]}}</view>
					</picker>
				</view>
			</view>
		</view>

		<view class="uni-title uni-common-pl">时间选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker mode="time" :value="time" start="09:01" end="21:01" @change="bindTimeChange">
						<view class="uni-input">{{time}}</view>
					</picker>
				</view>
			</view>
		</view>

		<view class="uni-title uni-common-pl">日期选择器</view>
		<view class="uni-list">
			<view class="uni-list-cell">
				<view class="uni-list-cell-left">
					当前选择
				</view>
				<view class="uni-list-cell-db">
					<picker mode="date" :value="date" :start="startDate" :end="endDate" @change="bindDateChange">
						<view class="uni-input">{{date}}</view>
					</picker>
				</view>
			</view>
		</view>
	</view>
</template>
```
```javascript
export default {
    data() {
        const currentDate = this.getDate({
            format: true
        })
        return {
            title: 'picker',
            array: ['中国', '美国', '巴西', '日本'],
            index: 0,
            date: currentDate,
            time: '12:01'
        }
    },
    computed: {
        startDate() {
            return this.getDate('start');
        },
        endDate() {
            return this.getDate('end');
        }
    },
    methods: {
        bindPickerChange: function(e) {
            console.log('picker发送选择改变，携带值为', e.target.value)
            this.index = e.target.value
        },
        bindDateChange: function(e) {
            this.date = e.target.value
        },
        bindTimeChange: function(e) {
            this.time = e.target.value
        },
        getDate(type) {
            const date = new Date();
            let year = date.getFullYear();
            let month = date.getMonth() + 1;
            let day = date.getDate();

            if (type === 'start') {
                year = year - 60;
            } else if (type === 'end') {
                year = year + 2;
            }
            month = month > 9 ? month : '0' + month;;
            day = day > 9 ? day : '0' + day;
            return `${year}-${month}-${day}`;
        }
    }
}
```

![uniapp](https://img-cdn-qiniu.dcloud.net.cn/uniapp/doc/img/picker.png?t=201857)

示例代码说明：以上示例代码从hello uni-app示例中复制，涉及的css样式在hello uni-app的app.vue和uni.css中

预览H5效果：使用浏览器的手机模式访问[https://uniapp.dcloud.io/h5/pages/component/picker/picker](https://uniapp.dcloud.io/h5/pages/component/picker/picker)

**注意**
- 在picker内容还在滚动时或滚动回弹动画还未结束时，点确定关闭弹出的picker，数据无法及时更新。需等待一下，或手动触停滚动再点确定。所有平台均如此
W
Update picker.md  
wanganxp 已提交
230 
- app-nvue 平台，mode 目前仅支持 ``selector`` ``time`` ``date``