Skip to content

Picker 选择器

Picker 组件为 popup 和 pickerView 的组合。

基本用法

columns 设置选项数据源,选项可以为字符串,也可以为对象,如果为对象则默认取 label 属性为选项内容进行渲染。label 设置左侧文本内容,v-model 设置选中项的值。label 可以不传。可以通过 label-width 设置标题宽度,默认为 '33%',监听 confirm 事件,获取选中值,传出一个 evnet 对象, event = { value, selectedItems },value 为绑定值,selectedItems 为选中选项的对象。

html
<wd-picker :columns="columns" label="单列选项" v-model="value" @confirm="handleConfirm" />
typescript
const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7'])
const value = ref('选项1')

function handleConfirm({ value }) {
  value.value = value
}

columns 选项为对象时,其数据结构为:

参数类型说明最低版本
valuestring / number / boolean选项值,如果 value 属性不存在,则使用 label 作为选项的值-
labelstring选项文本内容-
disabledboolean选项是否禁用-

禁用

设置 disabled 属性。

html
<wd-picker :columns="columns" label="禁用" v-model="value" disabled />
typescript
const value = ref('选项3')

const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7'])

只读

设置 readonly 属性。

html
<wd-picker :columns="columns" label="只读" v-model="value" readonly />

清空按钮

设置 clearable 属性。

html
<wd-picker :columns="columns" label="清空" v-model="value" clearable />

文案标题

设置 title 属性。

html
<wd-picker label="标题" :columns="columns" title="文案标题"/>

加载中

设置 loading 属性。

html
<wd-picker-view :columns="columns" loading />

多列

columns 属性设置为二维数组,value 为数组。

html
<wd-picker :columns="columns" label="多列" v-model="value" />
typescript
const value = ref(['中南大学', '软件工程'])

const columns = ref([
  ['中山大学', '中南大学', '华南理工大学'],
  ['计算机科学与技术', '软件工程', '通信工程', '法学', '经济学']
])

多级联动

传入 column-change 属性,其类型为 function,接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参,根据选中项和列下标进行判断,通过 pickerView 实例暴露出来的 setColumnData 方法修改其他列的数据源,当修改完成后需要执行 resolve() 告知组件修改完成以继续执行,如果 column-change 包含异步操作,也可以使组件按照异步顺序进行执行。

每次修改完后都需要调用 resolve() 通知组件。

html
<wd-picker
  :columns="columns"
  label="多列联动"
  v-model="value"
  :column-change="onChangeDistrict"
  :display-format="displayFormat"
 />
typescript
const district = {
  '0': [{ label: '北京', value: '110000' }, { label: '广东省', value: '440000' }],
  '110000': [{ label: '北京', value: '110100' }],
  '440000': [{ label: '广州市', value: '440100' }, { label: '韶关市', value: '440200' }, { label: '深圳市', value: '440300' }, { label: '珠海市', value: '440400' }, { label: '汕头市', value: '440500' }],
  '110100': [{ label: '东城区', value: '110101' }, { label: '西城区', value: '110102' }, { label: '朝阳区', value: '110105' }, { label: '丰台区', value: '110106' }, { label: '石景山区', value: '110107' }],
  '440100': [{ label: '荔湾区', value: '440103' }, { label: '越秀区', value: '440104' }, { label: '海珠区', value: '440105'}],
  '440200': [{ label: '武江区', value: '440203'}],
  '440300': [{ label: '罗湖区', value: '440303' }, { label: '福田区', value: '440304' }],
  '440400': [{ label: '香洲区', value: '440402' }, { label: '斗门区', value: '440403' }, { label: '金湾区', value: '440404' }],
  '440500': [{ label: '龙湖区', value: '440507' }, { label: '金平区', value: '440511' }]
}

const value = ref(['110000', '110100', '110102'])

const columns = ref([district[0], district[district[0][0].value], district[district[district[0][0].value][0].value]])

const onChangeDistrict = (pickerView, value, columnIndex, resolve) => {
  const item = value[columnIndex]
  if (columnIndex === 0) {
    pickerView.setColumnData(1, district[item.value])
    pickerView.setColumnData(2, district[district[item.value][0].value])
  } else if (columnIndex === 1) {
    pickerView.setColumnData(2, district[item.value])
  }
  resolve()
}

const displayFormat = (items) => {
  return items
    .map((item) => {
      return item.label
    })
    .join('-')
}

选择器大小

通过设置 size 修改选择器大小,将 size 设置为 'large' 时字号为 16px。

html
<wd-picker label="单列选项" size="large" v-model="value" :columns="columns" />

必填属性

设置 required 属性,展示必填样式。

html
<wd-picker label="必填属性" error :columns="columns" v-model="value" required/>

错误状态

设置 error 属性,选择器的值显示为红色。

html
<wd-picker label="单列选项" error :columns="columns" v-model="value"/>

值靠右展示

设置 align-right 属性,选择器的值靠右展示。

html
<wd-picker label="单列选项" align-right :columns="columns" v-model="value"/>

确定前校验

设置 before-confirm 函数,在用户点击确定按钮时,会执行 before-confirm 函数,并传入 valueresolvepicker 参数,可以对 value 进行校验,并通过 resolve 函数告知组件是否确定通过,resolve 接受1个 boolean 值,resolve(true) 表示选项通过,resolve(false) 表示选项不通过,不通过时不会关闭 picker弹窗。可以通过 picker 参数直接设置 loadingcolumns 等属性。

html
<wd-toast />

<wd-picker label="before-confirm" :columns="columns" v-model="value" :before-confirm="beforeConfirm" @confirm="handleConfirm" />
typescript
import { useToast } from '@/uni_modules/wot-design-uni'

const toast = useToast()

const beforeConfirm = (value, resolve, picker) => {
  picker.setLoading(true)
  setTimeout(() => {
    picker.setLoading(false)
    if (['选项2', '选项3'].indexOf(value) > -1) {
      resolve(false)
      toast.error('选项校验不通过,请重新选择')
    } else {
      resolve(true)
    }
  }, 2000)
}

const columns = ref(['选项1', '选项2', '选项3', '选项4', '选项5', '选项6', '选项7'])
const value = ref('')

const beforeConfirm = (value, resolve, picker) => {
  picker.setLoading(true)
  setTimeout(() => {
    picker.setLoading(false)
    if (['选项2', '选项3'].indexOf(value) > -1) {
      resolve(false)
      toast.error('选项校验不通过,请重新选择')
    } else {
      resolve(true)
    }
  }, 2000)
}

function handleConfirm({ value }) {
  value.value = value
}

唤起项插槽

开启 use-default-slot ,设置默认插槽修改唤起picker组件的形式。

html
<wd-picker :columns="columns" v-model="value" use-default-slot>
  <wd-button>插槽唤起</wd-button>
</wd-picker>

Attributes

参数说明类型可选值默认值最低版本
v-model选中项,如果为多列选择器,则其类型应为数组string / number / boolean / array---
columns选择器数据,可以为字符串数组,也可以为对象数组,如果为二维数组,则为多列选择器array---
loading加载中boolean-false-
loading-color加载的颜色,只能使用十六进制的色值写法,且不能使用缩写string-#4D80F0-
columns-heightpicker内部滚筒高number-231-
value-key选项对象中,value对应的 keystring-value-
label-key选项对象中,展示的文本对应的 keystring-label-
title弹出层标题string---
cancel-button-text取消按钮文案string-取消-
confirm-button-text确认按钮文案string-完成-
label选择器左侧文案string---
placeholder选择器占位符string-请选择-
disabled禁用boolean-false-
readonly只读boolean-false-
display-format自定义展示文案的格式化函数,返回一个字符串function---
column-change接收 pickerView 实例、选中项、当前修改列的下标、resolve 作为入参,根据选中项和列下标进行判断,通过 pickerView 实例暴露出来的 setColumnData 方法修改其他列的数据源。function---
size设置选择器大小stringlarge--
label-width设置左侧标题宽度string-33%-
error是否为错误状态,错误状态时右侧内容为红色boolean-false-
required表单属性,必填boolean-false-
align-right选择器的值靠右展示boolean-false-
use-label-slotlabel 使用插槽boolean-false-
use-default-slot使用默认插槽boolean-false-
before-confirm确定前校验函数,接收 (value, resolve, picker) 参数,通过 resolve 继续执行 picker,resolve 接收1个boolean参数function---
close-on-click-modal点击遮罩是否关闭boolean-true-
z-index弹窗层级number-15-
safe-area-inset-bottom弹出面板是否设置底部安全距离(iphone X 类型的机型)boolean-true-
ellipsis是否超出隐藏boolean-false-
prop表单域 model 字段名,在使用表单校验功能的情况下,该属性是必填的string---
rules表单验证规则,结合wd-form组件使用FormItemRule []-[]-
immediate-change是否在手指松开时立即触发picker-view的 change 事件。若不开启则会在滚动动画结束后触发 change 事件,1.2.25版本起提供,仅微信小程序和支付宝小程序支持。boolean-false1.2.25
clearable显示清空按钮boolean-false1.3.13

FormItemRule 数据结构

键名说明类型
required是否为必选字段boolean
message错误提示文案string
validator通过函数进行校验,可以返回一个 Promise 来进行异步校验(value, rule) => boolean | Promise
pattern通过正则表达式进行校验,正则无法匹配表示校验不通过RegExp

Events

事件名称说明参数最低版本
confirm点击右侧按钮触发{ value, selectedItems }, value 为选中值(多列则为数组),selectedItems为选中项(多列则为数组)-
cancel点击左侧按钮触发--
open打开选择器弹出层时触发--
clear点击清空按钮时触发-1.3.13

Methods

方法名称说明参数最低版本
open打开picker弹框--
close关闭picker弹框--

Slot

name说明最低版本
default使用默认插槽-
label左侧标题插槽-

外部样式类

类名说明最低版本
custom-class根节点样式-
custom-view-classpickerView 外部自定义样式-
custom-label-classlabel 外部自定义样式-
custom-value-classvalue 外部自定义样式-

源代码

文档
组件

Released under the MIT License.

Released under the MIT License.