从底部弹起的滚动选择器。支持五种选择器,通过mode来区分,分别是普通选择器,多列选择器,时间选择器,日期选择器,省市区选择器,默认是普通选择器。
1、普通选择器
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 时触发
picker在各平台的实现是有UI差异的,有的平台如百度、支付宝小程序的Android端是从中间弹出的;有的平台支持循环滚动如微信、百度小程序;有的平台没有取消按钮如App端。但均不影响功能使用。
2、多列选择器
mode = multiSelector
平台差异说明
App
H5
微信小程序
支付宝小程序
百度小程序
字节跳动小程序
QQ小程序
vue支持,nvue自2.4起支持
√
√
x
√
√
√
支付宝小程序 picker 组件不支持多列选择,可以使用 picker-view 组件替代。
属性说明
属性名
类型
默认值
说明
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
是否禁用
bug & tips
由于 JavaScript 的限制 vue 不能观测如下方式设置 value:this.value[0] = 0 (vue 注意事项),解决方式参考:hello-uniapp 示例
微信开发工具的pc模拟器有可能出现拖动数据错乱,使用真机正常
3、时间选择器
mode = time
平台差异说明
App
H5
微信小程序
支付宝小程序
百度小程序
字节跳动小程序
QQ小程序
√
√
√
√
√
√
√
时间选择在App端调用的是os的原生时间选择控件,在不同平台有不同的ui表现
属性说明
属性名
类型
默认值
说明
平台差异说明
value
String
表示选中的时间,格式为"hh:mm"
start
String
表示有效时间范围的开始,字符串格式为"hh:mm"
App 不支持
end
String
表示有效时间范围的结束,字符串格式为"hh:mm"
App 不支持
@change
EventHandle
value 改变时触发 change 事件,event.detail = {value: value}
@cancel
EventHandle
取消选择时触发
disabled
Boolean
false
是否禁用
4、日期选择器
mode = date
平台差异说明
App
H5
微信小程序
支付宝小程序
百度小程序
字节跳动小程序
QQ小程序
√
√
√
√
√
√
√
日期选择在App端调用的是os的原生日期选择控件,在不同平台有不同的ui表现。
属性说明
属性名
类型
默认值
说明
平台差异说明
value
String
0
表示选中的日期,格式为"YYYY-MM-DD"
start
String
表示有效日期范围的开始,字符串格式为"YYYY-MM-DD"
end
String
表示有效日期范围的结束,字符串格式为"YYYY-MM-DD"
fields
String
day
有效值 year,month,day,表示选择器的粒度
H5、App 2.6.3+、微信小程序、百度小程序、字节跳动小程序
@change
EventHandle
value 改变时触发 change 事件,event.detail = {value: value}
@cancel
EventHandle
取消选择时触发
disabled
Boolean
false
是否禁用
fields 有效值
值
说明
year
选择器粒度为年
month
选择器粒度为月份
day
选择器粒度为天
5、省市区选择器
mode = region
平台差异说明
App
H5
微信小程序
支付宝小程序
百度小程序
字节跳动小程序
QQ小程序
x
x
√
x
√
√
√
因省市区选择器包含大量数据,占用体积,并非所有应用都需要,且很多城市数据有自维护需求,所以在App和H5平台没有内置。可以基于多列picker或picker-view,自行填充城市数据,插件市场有较多类似插件,详见。注意基于多列picker方式的地区选择不能运行在支付宝小程序上,只有基于picker-view的可以全端运行。这些插件中,比较推荐的是SimpleJalon的地址联动选择插件,它可以同时兼容app-nvue、app-vue、h5、及各端小程序。
属性名
类型
默认值
说明
value
Array
[]
表示选中的省市区,默认选中每一列的第一个值
custom-item
String
可为每一列的顶部添加一个自定义的项
@change
EventHandle
value 改变时触发 change 事件,event.detail = {value: value}
@cancel
EventHandle
取消选择时触发
disabled
Boolean
false
是否禁用
以下示例代码,来自于hello uni-app项目,推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。
地区选择器
当前选择
{{array[index]}}
时间选择器
当前选择
{{time}}
日期选择器
当前选择
{{date}}
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}`;
}
}
}
示例代码说明:以上示例代码从hello uni-app示例中复制,涉及的css样式在hello uni-app的app.vue和uni.css中
//自己写的实例
//注意:省市区的值,要 {{ cityVal[0] }},{{ cityVal[1] }},{{ cityVal[2] }} 分开写
所在地区:
{{ cityVal[0] }},{{ cityVal[1] }},{{ cityVal[2] }}
请选择
export default {
data() {
return {
cityVal: [] //所在地区
}
},
methods: {
cityChange(e) { 省市区
this.cityVal = e.detail.value;
}
}
}
效果图
选择地区
6、注意
在picker内容还在滚动时或滚动回弹动画还未结束时,点确定关闭弹出的picker,数据无法及时更新。需等待一下,或手动触停滚动再点确定。所有平台均如此
如果需要在PC端使用picker,需注意pc端没有touchmove事件,可以配置H5模版,并引入touch-emulator.js来解决。hello uni-app的pc版也是使用了这个方案。
7、实例
7-1、普通的数据绑定
//页面
普通选择
{{index>-1?picker[index]:'禁止换行,超出容器部分会以 ... 方式截断'}}
//js
export default {
data() {
return {
index: -1,
picker: ['喵喵喵', '汪汪汪', '哼唧哼唧']
}
},
methods: {
PickerChange(e) {
this.index = e.detail.value
}
}
}
7-2、动态绑定数据
//页面
班级列表
{{ classList[classIndex].FClassName }}
//js
export default {
data() {
return {
classIndex: 0, //班级列表 -- 默认显示第一个班级的下标
classID: 0, //班级列表 -- 某班级ID
classList: [{'FID':56,'FClassName':'一年级1班'},{'FID':57,'FClassName':'二年级2班'},{'FID':58,'FClassName':'三年级3班'}]
}
},
methods: {
classListPChange(e) {
var thisIndex = e.detail.value;
this.classID = classList[thisIndex].FID;
this.classIndex = thisIndex;
}
}
}
:range-key="'FClassName'",FClassName要加单引号