Taroify

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 label="城市" rightIcon={<ArrowRight />} onClick={() => setOpenPicker(true)}>
        <Input readonly placeholder="选择城市" value={value} />
      </Field>
      <Popup open={openPicker} rounded placement="bottom" onClose={setOpenPicker}>
        <Popup.Backdrop />
        <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	选项改变时触发	单列：选中值，选中值对应的选项对象多列：所有列选中值，当前列对应的选项对象

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
—picker-background-color	var(—white)	-
—picker-toolbar-height	44px $hd*	-
—picker-title-font-size	var(—font-size-lg)	-
—picker-title-line-height	var(—line-height-md)	-
—picker-action-padding	0 var(—padding-md)	-
—picker-action-font-size	var(—font-size-md)	-
—picker-confirm-action-color	var(—text-link-color)	-
—picker-cancel-action-color	var(—gray-6)	-
—picker-swipe-transition-duration	800ms	-
—picker-column-transition-zero-duration	0	-
—picker-column-transition-switch-duration	200ms	-
—picker-column-transition-duration	var(—picker-swipe-transition-duration)	-
—picker-option-color	var(—black)	-
—picker-option-padding	0 var(—padding-base)	-
—picker-option-font-size	var(—font-size-lg)	-
—picker-option-disabled-opacity	0.3	-
—picker-option-height	44PX	-
—picker-loading-icon-color	var(—primary-color)	-
—picker-loading-mask-color	rgba(255, 255, 255, 0.9)	-