shop-wx/doc/wot-design-uni/docs/component/picker.md

Picker 选择器

Picker 组件为 popup 和 pickerView 的组合。

基本用法

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

<wd-picker :columns="columns" label="单列选项" v-model="value" @confirm="handleConfirm" />

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

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

当 columns 选项为对象时，其数据结构为：

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

禁用

设置 disabled 属性。

<wd-picker :columns="columns" label="禁用" v-model="value" disabled />

const value = ref('选项3')

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

只读

设置 readonly 属性。

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

清空按钮

设置 clearable 属性。

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

文案标题

设置 title 属性。

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

加载中

设置 loading 属性。

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

多列

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

<wd-picker :columns="columns" label="多列" v-model="value" />

const value = ref(['中南大学', '软件工程'])

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

多级联动

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

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

<wd-picker
  :columns="columns"
  label="多列联动"
  v-model="value"
  :column-change="onChangeDistrict"
  :display-format="displayFormat"
 />

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。

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

必填属性

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

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

错误状态

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

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

值靠右展示

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

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

确定前校验

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

<wd-toast />

<wd-picker label="before-confirm" :columns="columns" v-model="value" :before-confirm="beforeConfirm" @confirm="handleConfirm" />

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组件的形式。

<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-height	picker内部滚筒高	number	-	231	-
value-key	选项对象中，value对应的 key	string	-	value	-
label-key	选项对象中，展示的文本对应的 key	string	-	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	设置选择器大小	string	large	-	-
label-width	设置左侧标题宽度	string	-	33%	-
error	是否为错误状态，错误状态时右侧内容为红色	boolean	-	false	-
required	表单属性，必填	boolean	-	false	-
marker-side	必填标记位置	string	before / after	before	1.12.0
align-right	选择器的值靠右展示	boolean	-	false	-
use-label-slot	label 使用插槽	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	-	false	1.2.25
clearable	显示清空按钮	boolean	-	false	1.11.0
root-portal	是否从页面中脱离出来，用于解决各种 fixed 失效问题	boolean	-	false	1.11.0

FormItemRule 数据结构

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

Events

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

Methods

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

Slot

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

外部样式类

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