Picker 选择器

底部滑入式选择器组件，采用 WeUI 官方半屏弹窗结构，支持单列和多列选择。支持声明式和命令式两种调用方式。滚动列采用触摸交互，松手后自动归位到最近一项。

组件在 Vue 3/H5 与 uni-app 产物中都渲染完整的列区域；小程序端会将列项转换为原生 view 节点，触摸滚动和选中状态保持一致。

基础用法

通过 v-model:visible 控制显示，columns 设置列配置，title 设置标题。Picker 默认只显示底部官方样式的主确认按钮；需要顶部关闭图标时写入 show-close。点击确认触发 confirm 事件，回调参数为 (indexes, values)。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="请选择"
    show-close
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [
  {
    options: [
      { label: '选项一', value: 'a' },
      { label: '选项二', value: 'b' },
      { label: '选项三', value: 'c' },
    ],
  },
]

const onConfirm = (indexes: number[], values: (string | number)[]) => {
  console.log('选中', indexes, values)
}
</script>

多列选择

通过 columns 传入多列配置，每列独立的 options 与可选的初始 index。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示多列 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="请选择日期"
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [
  {
    options: [
      { label: '2024 年', value: 2024 },
      { label: '2025 年', value: 2025 },
      { label: '2026 年', value: 2026 },
    ],
  },
  {
    options: [
      { label: '1 月', value: 1 },
      { label: '2 月', value: 2 },
      { label: '3 月', value: 3 },
    ],
  },
  {
    options: [
      { label: '1 日', value: 1 },
      { label: '15 日', value: 15 },
      { label: '28 日', value: 28 },
    ],
    index: 1,
  },
]
</script>

带初始选中

通过 PickerColumn.index 设置每列的初始选中索引。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示初始选中 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="请选择"
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [
  {
    options: [
      { label: '选项一', value: 'a' },
      { label: '选项二', value: 'b' },
      { label: '选项三', value: 'c' },
      { label: '选项四', value: 'd' },
    ],
    index: 2,
  },
]
</script>

禁用选项

通过 PickerOption.disabled 标记选项为禁用，渲染时添加 weui-picker__item_disabled 样式。滚动停在禁用项时，Picker 会自动归位到最近的可选项；初始 index 指向禁用项时同样会自动避开。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示含禁用项 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="请选择"
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [
  {
    options: [
      { label: '可选一', value: 'a' },
      { label: '禁用项', value: 'b', disabled: true },
      { label: '可选三', value: 'c' },
    ],
  },
]
</script>

描述与关闭按钮

通过 desc 设置标题下的描述文字。Picker 默认不显示左上角关闭按钮，写入 show-close（或 :show-close="true"）后才显示；关闭按钮默认文案为官方的“关闭”。

查看代码

vue

<template>
  <weui-picker
    v-model:visible="show"
    title="请选择地区"
    desc="请选择一个常用城市"
    show-close
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const show = ref(false)
const columns = [{ options: [{ label: '北京', value: 'beijing' }] }]
const onConfirm = (indexes: number[], values: (string | number)[]) => {
  console.log(indexes, values)
}
</script>

自定义关闭与确认文案

通过官方命名的 close-text 和 confirm-text 自定义关闭/确认按钮文字。cancel-text 仍可作为旧版本兼容别名。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示自定义文案 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="请选择"
    show-close
    close-text="返回"
    confirm-text="完成"
    :columns="columns"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [
  {
    options: [
      { label: '选项一', value: 'a' },
      { label: '选项二', value: 'b' },
    ],
  },
]
</script>

禁用遮罩点击

通过 :mask-closable="false" 禁用点击遮罩关闭，用户必须点击关闭或确定。

查看代码

vue

<template>
  <weui-button type="primary" @click="show = true">显示 Picker</weui-button>
  <weui-picker
    v-model:visible="show"
    title="点击遮罩不关闭"
    show-close
    :mask-closable="false"
    :columns="columns"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { PickerColumn } from 'weui-uniapp-design'

const show = ref(false)
const columns: PickerColumn[] = [{ options: [{ label: '选项一', value: 'a' }] }]
</script>

命令式调用

通过 Picker.show(options) 命令式调用，无需在模板中声明组件。返回 Promise，确定时 resolve { action: 'confirm', indexes, values }，取消/遮罩点击时 resolve { action: 'cancel', indexes: [], values: [] }。

查看代码

vue

<template>
  <weui-overlay-host />
  <weui-button type="primary" @click="showImp">Picker.show</weui-button>
</template>

<script setup lang="ts">
import { Picker, type PickerColumn } from 'weui-uniapp-design'

const columns: PickerColumn[] = [
  {
    options: [
      { label: '选项一', value: 'a' },
      { label: '选项二', value: 'b' },
    ],
  },
]

const showImp = async () => {
  const result = await Picker.show({ title: '命令式选择', columns })
  if (result.action === 'confirm') {
    console.log('选中', result.indexes, result.values)
  }
}
</script>

Attributes

参数	说明	类型	默认值
visible (v-model)	是否显示	boolean	false
columns	多列配置	PickerColumn[]	[]
title	标题	string	—
desc	标题下的描述文字	string	—
show-close	是否显示左上角关闭按钮；写入该布尔属性即可启用	boolean	false
close-text	关闭按钮文字	string	'关闭'
cancel-text	旧版取消文字兼容别名（`close-text` 优先）	string	—
confirm-text	确定按钮文字	string	'确定'
mask-closable	点击遮罩是否关闭	boolean	true
ext-class	自定义附加类名	string	—
z-index	z-index（命令式调用时由 overlay-host 注入）	number	—

PickerColumn

字段	说明	类型	默认值
options	列选项	PickerOption[]	—
index	初始选中索引	number	0

PickerOption

字段	说明	类型	默认值
label	显示文字	string	—
value	选项值	string \| number	—
disabled	是否禁用；不会成为当前选中项	boolean	false

Events

事件名	说明	回调参数
update:visible	显示状态变化时触发	(value: boolean)
change	列滚动归位后触发（每列独立）	(indexes: number[], values: (string\|number)[])
confirm	点击确定时触发	(indexes: number[], values: (string\|number)[])
cancel	点击取消时触发	—
close	关闭时触发	—

命令式 API

Picker.show(options): `Promise<PickerShowResult>`

显示选择器。

参数	说明	类型	默认值
title	标题	string	—
desc	标题下的描述文字	string	—
columns	多列配置	PickerColumn[]	—
showClose	是否显示左上角关闭按钮	boolean	false
closeText	关闭按钮文字	string	'关闭'
cancelText	旧版取消文字兼容别名（`closeText` 优先）	string	—
confirmText	确定按钮文字	string	'确定'
maskClosable	点击遮罩是否关闭	boolean	true
extClass	自定义附加类名	string	—

返回 Promise，resolve 值结构：

字段	说明	类型
action	触发动作	'confirm' \| 'cancel'
indexes	各列选中索引（cancel 时为空数组）	number[]
values	各列选中值（cancel 时为空数组）	(string\|number)[]

Picker 选择器 ​

基础用法 ​

多列选择 ​

带初始选中 ​

禁用选项 ​

描述与关闭按钮 ​

自定义关闭与确认文案 ​

禁用遮罩点击 ​

命令式调用 ​

Attributes ​

PickerColumn ​

PickerOption ​

Events ​

命令式 API ​

Picker.show(options): Promise<PickerShowResult> ​

Picker 选择器

基础用法

多列选择

带初始选中

禁用选项

描述与关闭按钮

自定义关闭与确认文案

禁用遮罩点击

命令式调用

Attributes

PickerColumn

PickerOption

Events

命令式 API

Picker.show(options): `Promise<PickerShowResult>`