• Vant React

Picker 选择器

介绍

提供多个选项集合供用户选择,支持单列选择和多列级联,通常与弹出层组件配合使用。

引入

import { Picker } from "@taroify/core";

代码演示

基础用法

选项配置

Picker 组件通过 Picker.Option 属性配置选项数据。

顶部栏

顶部栏包含标题、确认按钮和取消按钮,点击确认按钮触发 onConfirm 事件,点击取消按钮触发 onCancel 事件。

function BasicPicker() {
  return (
    <>
      <Toast id="toast" />
      <Picker onChange={(value) => Toast.open(`当前值:${value}`)}>
        <Picker.Toolbar>
          <Picker.Button>取消</Picker.Button>
          <Picker.Title>标题</Picker.Title>
          <Picker.Button>确认</Picker.Button>
        </Picker.Toolbar>
        <Picker.Column>
          <Picker.Option>杭州</Picker.Option>
          <Picker.Option>宁波</Picker.Option>
          <Picker.Option>温州</Picker.Option>
          <Picker.Option>绍兴</Picker.Option>
          <Picker.Option>湖州</Picker.Option>
          <Picker.Option>嘉兴</Picker.Option>
          <Picker.Option>金华</Picker.Option>
        </Picker.Column>
      </Picker>
    </>
  )
}

默认选中项

单列选择时,可以通过 defaultValue 属性设置初始选中项的值。

function DefaultPicker() {
  return (
    <>
      <Toast id="toast" />
      <Picker defaultValue="温州" onChange={(value) => Toast.open(`当前值:${value}`)}>
        <Picker.Toolbar>
          <Picker.Button>取消</Picker.Button>
          <Picker.Title>标题</Picker.Title>
          <Picker.Button>确认</Picker.Button>
        </Picker.Toolbar>
        <Picker.Column>
          <Picker.Option>杭州</Picker.Option>
          <Picker.Option>宁波</Picker.Option>
          <Picker.Option>温州</Picker.Option>
          <Picker.Option>绍兴</Picker.Option>
          <Picker.Option>湖州</Picker.Option>
          <Picker.Option>嘉兴</Picker.Option>
          <Picker.Option>金华</Picker.Option>
        </Picker.Column>
      </Picker>
    </>
  )
}

多列选择

function PickerWithMultiColumns() {
  return (
    <>
      <Toast id="toast" />
      <Picker onConfirm={(values) => Toast.open(`当前值:${_.join(values, ",")}`)}>
        <Picker.Toolbar>
          <Picker.Button>取消</Picker.Button>
          <Picker.Title>标题</Picker.Title>
          <Picker.Button>确认</Picker.Button>
        </Picker.Toolbar>
        <Picker.Column>
          <Picker.Option>周一</Picker.Option>
          <Picker.Option>周二</Picker.Option>
          <Picker.Option>周三</Picker.Option>
          <Picker.Option>周四</Picker.Option>
          <Picker.Option>周五</Picker.Option>
        </Picker.Column>
        <Picker.Column>
          <Picker.Option>上午</Picker.Option>
          <Picker.Option>下午</Picker.Option>
          <Picker.Option>晚上</Picker.Option>
        </Picker.Column>
      </Picker>
    </>
  )
}

禁用选项

通过设置 disabled 来禁用该选项。

function DisabledPicker() {
  return (
    <Picker>
      <Picker.Toolbar>
        <Picker.Button>取消</Picker.Button>
        <Picker.Title>标题</Picker.Title>
        <Picker.Button>确认</Picker.Button>
      </Picker.Toolbar>
      <Picker.Column>
        <Picker.Option disabled>杭州</Picker.Option>
        <Picker.Option>宁波</Picker.Option>
        <Picker.Option>温州</Picker.Option>
      </Picker.Column>
    </Picker>
  )
}

加载状态

若选择器数据是异步获取的,可以通过 loading 属性显示加载提示。

function LoadingPicker() {
  return (
    <Picker loading>
      <Picker.Toolbar>
        <Picker.Button>取消</Picker.Button>
        <Picker.Title>标题</Picker.Title>
        <Picker.Button>确认</Picker.Button>
      </Picker.Toolbar>
      <Picker.Column>
        <Picker.Option>浙江</Picker.Option>
        <Picker.Option>福建</Picker.Option>
      </Picker.Column>
      <Picker.Column>
        <Picker.Option>杭州</Picker.Option>
        <Picker.Option>宁波</Picker.Option>
        <Picker.Option>温州</Picker.Option>
        <Picker.Option>嘉兴</Picker.Option>
        <Picker.Option>湖州</Picker.Option>
      </Picker.Column>
    </Picker>
  )
}

搭配弹出层使用

在实际场景中,Picker 通常作为用于辅助表单填写,可以搭配 Popup 和 Field 实现该效果。

function PickerPopup() {
  const [value, setValue] = useState("")
  const [openPicker, setOpenPicker] = useState(false)

  return (
    <>
      <Field
        value={value}
        label="城市"
        placeholder="选择城市"
        readonly
        rightIcon={<ArrowRight />}
        onClick={() => setOpenPicker(true)}
      />
      <Popup open={openPicker} rounded placement="bottom" onClose={setOpenPicker}>
        <Picker
          onCancel={() => setOpenPicker(false)}
          onConfirm={(values) => {
            setValue(values)
            setOpenPicker(false)
          }}
        >
          <Picker.Toolbar>
            <Picker.Button>取消</Picker.Button>
            <Picker.Title>标题</Picker.Title>
            <Picker.Button>确认</Picker.Button>
          </Picker.Toolbar>
          <Picker.Column>
            <Picker.Option>杭州</Picker.Option>
            <Picker.Option>宁波</Picker.Option>
            <Picker.Option>温州</Picker.Option>
            <Picker.Option>绍兴</Picker.Option>
            <Picker.Option>湖州</Picker.Option>
            <Picker.Option>嘉兴</Picker.Option>
            <Picker.Option>金华</Picker.Option>
          </Picker.Column>
        </Picker>
      </Popup>
    </>
  )
}

API

Picker Props

参数 说明 类型 默认值
defaultValue 默认选中的值 any | any[] -
value 选中的值 any | any[] -
loading 是否显示加载状态 boolean false
readonly 是否为只读状态,只读状态下无法切换选项 boolean false
siblingCount 可见的选项相邻个数 number 3

Picker Events

当选择器有多列时,事件回调参数会返回数组。

事件名 说明 回调参数
onConfirm 点击完成按钮时触发 单列:选中值,选中值对应的选项对象
多列:所有列选中值,所有列选中值对应的选项对象
onCancel 点击取消按钮时触发 单列:选中值,选中值对应的选项对象
多列:所有列选中值,所有列选中值对应的选项对象
onChange 选项改变时触发 单列:选中值,选中值对应的选项对象
多列:所有列选中值,当前列对应的选项对象