Picker selector

introduce

Provides multiple option sets for users to choose from, supporting single column selection, multi-column selection and cascading selection. It is usually used in conjunction with the popup layer (/popup) component.

Code Demo

Basic usage

Options configuration

The Picker component configures option data through the columns attribute, which is an array containing strings or objects.

Top bar

The top bar contains a title, a confirm button and a cancel button. Clicking the confirm button triggers the confirm event, and clicking the cancel button triggers the cancel event.

<z-picker
   title="title"
   :columns="columns"
   @confirm="onConfirm"
   @cancel="onCancel"
   @change="onChange"
/>
import { useToast } from '../../uni_modules/zebra-ui'
const toast = useToast()
const columns = [
   { text: 'Hangzhou', value: 'Hangzhou' },
   { text: 'Ningbo', value: 'Ningbo' },
   { text: 'Wenzhou', value: 'Wenzhou' },
   { text: 'Shaoxing', value: 'Shaoxing' },
   { text: 'Huzhou', value: 'Huzhou' }
]
const onConfirm = ({ selectedValues }: any) => {
   toast.showToast(`Current value: ${selectedValues.join(',')}`)
}
const onChange = ({ selectedValues }: any) => {
   toast.showToast(`Current value: ${selectedValues.join(',')}`)
}
const onCancel = () => toast.showToast('Cancel')

Used with pop-up layer

In actual scenarios, Picker is usually used to assist in form filling, and can be used with Popup and Field to achieve this effect.

<z-field
   v-model="fieldValue"
   is-link
   readonly
   label="city"
   placeholder="Select city"
   @click="showPicker = true"
   @click-input="showPicker = true"
/>
<z-popup v-model:show="showPicker" round position="bottom">
   <z-picker
     :columns="columns"
     @cancel="showPicker = false"
     @confirm="onConfirmInput"
   />
</z-popup>

Two-way binding

v-model can be used to bind the values of the currently selected item. When the value bound to v-model is modified, the selected state of the Picker will also change accordingly.

The value of v-model is an array. The first digit of the array corresponds to the value of the selected item in the first column, the second digit corresponds to the value of the selected item in the second column, and so on.

<z-picker v-model="selectedValues" title="title" :columns="columns" />

###Multiple column selection

The columns property can configure multi-column selection in the form of a two-dimensional array.

<z-picker title="title" :columns="columnsMore" />
const columnsMore = [
   [
     { text: 'Monday', value: 'Monday' },
     { text: 'Tuesday', value: 'Tuesday' },
     { text: 'Wednesday', value: 'Wednesday' },
     { text: 'Thursday', value: 'Thursday' },
     { text: 'Friday', value: 'Friday' }
   ],
   [
     { text: 'Morning', value: 'Morning' },
     { text: 'afternoon', value: 'Afternoon' },
     { text: 'Evening', value: 'Evening' }
   ]
]

Cascade selection

The effect of option cascading can be achieved using the children field of columns. If there are many cascading levels, it is recommended to use Cascader cascading option component.

<z-picker title="title" :columns="columnsCascade" />
const columnsCascade = [
   {
     text: 'Zhejiang',
     value: 'Zhejiang',
     children: [
       {
         text: 'Hangzhou',
         value: 'Hangzhou',
         children: [
           { text: '西湖区', value: 'Xihu' },
           { text: 'Yuhang District', value: 'Yuhang' }
         ]
       },
       {
         text: 'Wenzhou',
         value: 'Wenzhou',
         children: [
           { text: 'Lucheng District', value: 'Lucheng' },
           { text: 'Ouhai District', value: 'Ouhai' }
         ]
       }
     ]
   },
   {
     text: 'Fujian',
     value: 'Fujian',
     children: [
       {
         text: 'Fuzhou',
         value: 'Fuzhou',
         children: [
           { text: 'Gulou District', value: 'Gulou' },
           { text: 'Taijiang District', value: 'Taijiang' }
         ]
       },
       {
         text: 'Xiamen',
         value: 'Xiamen',
         children: [
           { text: 'Siming District', value: 'Siming' },
           { text: 'Haicang District', value: 'Haicang' }
         ]
       }
     ]
   }
]

The data nesting depth of cascade selection needs to be consistent. If some options have no sub-options, empty strings can be used as placeholders.

Disable option

Options can be object structures, which can be disabled by setting disabled.

<z-picker :columns="columnsDisabled" />
const columnsDisabled = [
   { text: 'Hangzhou', value: 'Hangzhou', disabled: true },
   { text: 'Ningbo', value: 'Ningbo' },
   { text: 'Wenzhou', value: 'Wenzhou' }
]

Loading status

If the selector data is obtained asynchronously, the loading prompt can be displayed through the loading attribute.

<z-picker :loading="loading" />
import { ref } from 'vue';
const loading = ref(true);

Customize the structure of Columns

<z-picker
   title="title"
   :columns="columnsCustom"
   :columns-field-names="customFieldName"
/>
const columnsCustom = [
   {
     cityName: 'Zhejiang',
     cities: [
       {
         cityName: 'Hangzhou',
         cities: [{ cityName: 'Xihu District' }, { cityName: 'Yuhang District' }]
       },
       {
         cityName: 'Wenzhou',
         cities: [{ cityName: 'Lucheng District' }, { cityName: 'Ouhai District' }]
       }
     ]
   },
   {
     cityName: 'Fujian',
     cities: [
       {
         cityName: 'Fuzhou',
         cities: [{ cityName: 'Gulou District' }, { cityName: 'Taijiang District' }]
       },
       {
         cityName: 'Xiamen',
         cities: [{ cityName: 'Siming District' }, { cityName: 'Haicang District' }]
       }
     ]
   }
]
const customFieldName = {
   text: 'cityName',
   value: 'cityName',
   children: 'cities'
}

API

Props

ParametersDescriptionTypeDefault value
v-modelThe value corresponding to the currently selected itemnumber | string-
columnsObject array, configure the data displayed in each columnPickerOption | PickerOption[][]
columns-field-namesCustom fields in the columns structureobject{ text: 'text', value: 'value', children: 'children' }
titleTop column titlestring-
confirm-button-textConfirm button text, set to an empty string to hide the buttonstringConfirm
cancel-button-textCancel button text, set to an empty string to hide the buttonstringCancel
toolbar-positionTop bar position, optional value is bottomstringtop
loadingwhether to display loading statusbooleanfalse
readonlyWhether it is in read-only state. Options cannot be switched in read-only statebooleanfalse
show-toolbarWhether to display the top barbooleantrue
option-heightoption height, supports rpxUnit, default pxnumber | string44
visible-option-numNumber of visible optionsnumber | string6
swipe-durationThe duration of inertial scrolling during fast swiping, unit msnumber | string1000

Events

Event nameDescriptionCallback parameters
confirmTriggered when the completion button is clicked{ selectedValues, selectedOptions, selectedIndexes }
cancelTriggered when the cancel button is clicked{ selectedValues, selectedOptions, selectedIndexes }
changeTriggered when the selected option changes{ selectedValues, selectedOptions, selectedIndexes, columnIndex }
click-optionTriggered when an option is clicked{ currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex }
scroll-intoTriggered when the user scrolls an option to the middle selection area by clicking or dragging{ currentOption, columnIndex }

Slots

NameDescriptionParameters
toolbarCustomize the entire top bar content-
titleCustom title content-
confirmCustomize the confirmation button content-
cancelCustomize cancel button content-
optionCustom option contentoption: PickerOption, index: number
columns-topCustomize the content above the options-
columns-bottomCustomize the content below the options-

PickerOption data structure

Key nameDescriptionType
textoption text contentstring | number
valueThe value corresponding to the optionstring | number
disabledWhether to disable the optionboolean
childrenCascading optionsPickerOption
classNameoption extra class namestring | Array | object

method

Through ref, you can get the Picker instance and call the instance method.

Method nameDescriptionParametersReturn value
confirmStop inertial scrolling and trigger the confirm event--
getSelectedOptionsGet the currently selected options-(PickerOption | undefined)

Theme customization

Style variables

The component provides the following CSS variables, which can be used to customize styles. For usage, please refer to ConfigProvider component.

NameDefaultDescription
--z-picker-backgroundvar(--z-background-2)-
--z-picker-toolbar-height88rpx-
--z-picker-title-font-sizevar(--z-font-size-lg)-
--z-picker-title-line-heightvar(--z-line-height-md)-
--z-picker-action-padding0 var(--z-padding-md)-
--z-picker-action-font-sizevar(--z-font-size-md)-
--z-picker-confirm-action-colorvar(--z-primary-color)-
--z-picker-cancel-action-colorvar(--z-text-color-2)-
--z-picker-option-padding0 var(--z-padding-base)-
--z-picker-option-font-sizevar(--z-font-size-lg)-
--z-picker-option-text-colorvar(--z-text-color)-
--z-picker-option-disabled-opacity0.3-
--z-picker-mask-colorlinear-gradient-
--z-picker-loading-icon-colorvar(--z-primary-color)-
--z-picker-loading-mask-colorrgba(255, 255, 255, 0.9)-