# Picker 选择器

选择器主要用于选项的选取,分为单列(type='single'),多列(type='multi'),多列联动(type='multi-auto')三种类型

# 平台差异说明

App H5 微信小程序 支付宝小程序 百度小程序 字节小程序 QQ小程序

# 示例

# 基础用法

该组件通过items属性来接收选择项,而不同类型的选择器要求items传入的格式不一样。支持单项选择,多项选择,以及多项关联选择。

通过v-model绑定一个布尔值变量,用于控制组件的弹出与收起。 item对象包含一个keyField (每项绑定的key值),默认为'id',包含一个displayField(每项显示的文本),默认为'text',方便接入后端数据。

  • 注意: default-value数组的长度,必须与列数相同,否则无效。
  • 单列模式 如设置default-value为[1]表示默认选中第2个(从0开始),[5]表示选中第6个。
  • 多列模式 如设置default-value为[1, 3]表示第一列默认选中第2个,第二列默认选中第4个。

# 单列选择 type='single'

items要求的格式是一维数组,格式如下:

items: [
  { id: 'beijing', text: '北京' },
  { id: 'shanghai', text: '上海' },
  { id: 'zhuhai', text: '珠海' }
]
1
2
3
4
5
<pi-picker
  v-model="pickerOptions.show"
  :items="pickerOptions.items"
  :type="pickerOptions.type"
  :default-value="pickerOptions.defaultValue"
  :popup-select="{
    showTitle: true,
    title: pickerOptions.title,
    borderRadius: '24rpx 24rpx 0 0',
    appendToBody: true
  }"
  @confirm="handlePickerConfirm"
/>

export default {
   data() {
    return {
      pickerOptions: {
        key: '',
        show: true,
        items: items,
        type: 'single',
        defaultValue: [1],
        title: 'default-value = [1]'
      }
    }
  }
}
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

# 多列选择 type='multi'

items要求的格式是二维数组,格式如下:

items: [
  [
    { id: 'china', text: '中国' },
    { id: 'us', text: '美国' },
    { id: 'us', text: '英国' },
    { id: 'us', text: '俄罗斯' }
  ],
  [
    { id: 'male', text: '男' },
    { id: 'famale', text: '女' },
    { id: 'unknown', text: '未知' }
  ]
]
1
2
3
4
5
6
7
8
9
10
11
12
13
<pi-picker
  v-model="pickerOptions.show"
  :items="pickerOptions.items"
  :type="pickerOptions.type"
  :default-value="pickerOptions.defaultValue"
  :popup-select="{
    showTitle: true,
    title: pickerOptions.title,
    borderRadius: '24rpx 24rpx 0 0',
    appendToBody: true
  }"
  @confirm="handlePickerConfirm"
/>

export default {
   data() {
    return {
      pickerOptions: {
        key: '',
        show: true,
        items: items,
        type: 'multi',
        defaultValue: [1, 1],
        title: 'default-value = [1, 1]'
      }
    }
  }
}
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

# 多列关联选择 type='multi-auto'

items要求的格式是一维数组,每个item下可选有一个children数组,代表该选项下一栏的数据,格式如下:

items: [
  {
   id: 'partyMember',
   text: '党员',
   children: [
     { id: 'shuji', text: '书记' },
     { id: 'member', text: '支书' },
     { id: 'committee', text: '村委员' }
   ]
 },
 {
   id: 'member',
   text: '团员',
   children: [
     { id: 'header', text: '队长' },
     { id: 'pacesetter', text: '标兵' }
   ]
 },
 {
   id: 'qunzhong',
   text: '群众',
   children: [
     {
       id: 'boss',
       text: '老板',
       children: [
         { id: 'person1', text: '张三' },
         { id: 'person2', text: '李四' },
         { id: 'person3', text: '王五' },
         { id: 'person4', text: '赵六' }
       ]
     },
     { id: 'worker', text: '打工仔' },
     { id: 'farmer', text: '农民' }
   ]
 }
]
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
<pi-picker
  v-model="pickerOptions.show"
  :items="pickerOptions.items"
  :type="pickerOptions.type"
  :default-value="pickerOptions.defaultValue"
  :popup-select="{
    showTitle: true,
    title: pickerOptions.title,
    borderRadius: '24rpx 24rpx 0 0',
    appendToBody: true
  }"
  @confirm="handlePickerConfirm"
/>

export default {
   data() {
    return {
      pickerOptions: {
        key: '',
        show: true,
        items:  items,
        type: 'multi-auto',
        defaultValue: [2, 0, 2],
        title: 'default-value = [2, 0, 2]'
      }
    }
  }
}
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

# popupSelect配置

Picker 外层弹窗使用 PopupSelect 组件实现,所以提供 popupSelect 属性定义弹窗属性,如标题、边框、高度等,详细请见popupSelect配置项

<pi-picker
  v-model="pickerOptions.show"
  :items="pickerOptions.items"
  :type="pickerOptions.type"
  :default-value="pickerOptions.defaultValue"
  :popup-select="{
    showTitle: true,
    title: pickerOptions.title,
    borderRadius: '24rpx 24rpx 0 0',
    titlePadding: '32rpx',
    height: '80%',
    toolbarPosition: 'top'
  }"
  @confirm="handlePickerConfirm"
/>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 自定义按钮

可通过confirmBtn:设置确定按钮的样式;

可通过cancelBtn:设置取消按钮的样式

<pi-picker
  v-model="pickerOptions.show"
  :items="pickerOptions.items"
  :type="pickerOptions.type"
  :default-value="pickerOptions.defaultValue"
  :confirm-btn="{ show: true, type: 'warn', round: true }"
  :cancel-btn="{ show: true, type: 'line', round: true }"
  @confirm="handlePickerConfirm"
/>
1
2
3
4
5
6
7
8
9

# API

# Props

名称 描述 类型 必选 默认值
value 初始值 false -
customStyle 自定义样式 Object false {}
customClass 自定义样式类 String false ''
type 选择器类型, 单列为'single', 多列为'multi', 多列联动为'multi-auto' String false 'single'
items 选项列表 Array false []
keyField 选项id字段 String false 'id'
displayField 选项显示字段 String false 'text'
childField 自定义多列联动模式的children属性名 String false 'children'
defaultValue 默认值,单选时传Object,多选时传Array Object/Array false null
itemHeight 行高 单位默认rpx String/Number false 110
itemStyle 行样式 Object false {}
showItemBottomBorder 是否显示item下边框 Boolean false true
popupSelect 弹窗的配置 Object false popupSelect配置项
popup 弹窗的配置 Object false popup配置项
confirmBtn 弹窗的配置 Object false confirmBtn配置项
cancelBtn 弹窗的配置 Object false cancelBtn配置项

# ConfirmBtn Props

提示

以下属性覆盖pi-button配置,其余属性参考button配置项

名称 描述 类型 必选 默认值
show 是否显示确认按钮 Boolean false true
text 确认文案 String false '确认'
width 确认按钮宽度 String | Number false 100%
type 确认按钮预置样式 'default' 'primary' 'warn' 'secondary' 'line' false 'primary'

# CancelBtn Props

提示

以下属性覆盖pi-button配置,其余属性参考button配置项

名称 描述 类型 必选 默认值
show 是否显示取消按钮 Boolean false false
text 取消文案 String false '取消'
width 取消按钮宽度 String | Number false 100%
type 取消按钮预置样式 'default' 'primary' 'warn' 'secondary' 'line' false 'secondary'

# Events

事件名 描述 参数
close 弹窗关闭 -
confirm 点击确定按钮时触发 this.pickerValue

# Slots

名称 描述 插槽内容
title 标题 默认:prop tite
header 顶部区域 -
footer 底部区域 -

# Methods

Method Description Parameters
handleCancel 取消选择 -
handleConfirm 确认选择 -
Last updated: 2021/9/8 上午10:27:00
10:44