14 KiB
Picker Selector
The Picker component is a combination of popup and pickerView.
Basic Usage
Set the columns property to configure the option data source. Options can be strings or objects. If they are objects, the label property is used by default for rendering the option content. The label property sets the left-side text content, and v-model sets the selected value. The label can be omitted. The title width can be set via label-width, which defaults to '33%'. Listen to the confirm event to get the selected value, which returns an event object: event = { value, selectedItems }. value is the bound value, and selectedItems is the selected option object(s).
<wd-picker :columns="columns" label="Single Column" v-model="value" @confirm="handleConfirm" />
const columns = ref(['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5', 'Option 6', 'Option 7'])
const value = ref('Option 1')
function handleConfirm({ value }) {
value.value = value
}
When columns options are objects, their data structure is as follows:
| Parameter | Type | Description | Minimum Version |
|---|---|---|---|
| value | string / number / boolean | Option value. If the value property is missing, label is used as the value. |
- |
| label | string | Option text content | - |
| disabled | boolean | Whether the option is disabled | - |
Disabled
Set the disabled property.
<wd-picker :columns="columns" label="Disabled" v-model="value" disabled />
const value = ref('Option 3')
const columns = ref(['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5', 'Option 6', 'Option 7'])
Readonly
Set the readonly property.
<wd-picker :columns="columns" label="Readonly" v-model="value" readonly />
Clear Button
Set the clearable property.
<wd-picker :columns="columns" label="Clear" v-model="value" clearable />
Title
Set the title property.
<wd-picker label="Title" :columns="columns" title="Picker Title"/>
Loading
Set the loading property.
<wd-picker-view :columns="columns" loading />
Multiple Columns
Set the columns property as a two-dimensional array, and value as an array.
<wd-picker :columns="columns" label="Multiple Columns" v-model="value" />
const value = ref(['Central South University', 'Software Engineering'])
const columns = ref([
['Sun Yat-sen University', 'Central South University', 'South China University of Technology'],
['Computer Science', 'Software Engineering', 'Communication Engineering', 'Law', 'Economics']
])
Cascading
Pass the column-change property, which is a function that receives the pickerView instance, selected item, current column index, and resolve as parameters. Based on the selected item and column index, modify the data source of other columns using the setColumnData method exposed by the pickerView instance. After modification, call resolve() to notify the component that the modification is complete. If column-change contains asynchronous operations, the component will execute them in order.
resolve()must be called after each modification.
<wd-picker
:columns="columns"
label="Cascading"
v-model="value"
:column-change="onChangeDistrict"
:display-format="displayFormat"
/>
const district = {
'0': [{ label: 'Beijing', value: '110000' }, { label: 'Guangdong', value: '440000' }],
'110000': [{ label: 'Beijing', value: '110100' }],
'440000': [{ label: 'Guangzhou', value: '440100' }, { label: 'Shaoguan', value: '440200' }, { label: 'Shenzhen', value: '440300' }, { label: 'Zhuhai', value: '440400' }, { label: 'Shantou', value: '440500' }],
'110100': [{ label: 'Dongcheng District', value: '110101' }, { label: 'Xicheng District', value: '110102' }, { label: 'Chaoyang District', value: '110105' }, { label: 'Fengtai District', value: '110106' }, { label: 'Shijingshan District', value: '110107' }],
'440100': [{ label: 'Liwan District', value: '440103' }, { label: 'Yuexiu District', value: '440104' }, { label: 'Haizhu District', value: '440105'}],
'440200': [{ label: 'Wujiang District', value: '440203'}],
'440300': [{ label: 'Luohu District', value: '440303' }, { label: 'Futian District', value: '440304' }],
'440400': [{ label: 'Xiangzhou District', value: '440402' }, { label: 'Doumen District', value: '440403' }, { label: 'Jinwan District', value: '440404' }],
'440500': [{ label: 'Longhu District', value: '440507' }, { label: 'Jinping District', 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('-')
}
Picker Size
Modify the picker size by setting size. When size is set to 'large', the font size becomes 16px.
<wd-picker label="Single Column" size="large" v-model="value" :columns="columns" />
Required
Set the required property to display the required style.
<wd-picker label="Required" error :columns="columns" v-model="value" required/>
Error State
Set the error property to display the picker value in red.
<wd-picker label="Single Column" error :columns="columns" v-model="value"/>
Right-Aligned Value
Set the align-right property to right-align the picker value.
<wd-picker label="Single Column" align-right :columns="columns" v-model="value"/>
Pre-Confirmation Validation
Set the before-confirm function. When the user clicks the "Confirm" button, the before-confirm function is executed, receiving value, resolve, and picker parameters. You can validate value and notify the component whether the validation passes via resolve. resolve accepts a boolean value: resolve(true) indicates validation passes, while resolve(false) indicates validation fails (the picker popup will not close). Properties like loading and columns can be directly set via the picker parameter.
<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 (['Option 2', 'Option 3'].indexOf(value) > -1) {
resolve(false)
toast.error('Validation failed. Please reselect.')
} else {
resolve(true)
}
}, 2000)
}
const columns = ref(['Option 1', 'Option 2', 'Option 3', 'Option 4', 'Option 5', 'Option 6', 'Option 7'])
const value = ref('')
const beforeConfirm = (value, resolve, picker) => {
picker.setLoading(true)
setTimeout(() => {
picker.setLoading(false)
if (['Option 2', 'Option 3'].indexOf(value) > -1) {
resolve(false)
toast.error('Validation failed. Please reselect.')
} else {
resolve(true)
}
}, 2000)
}
function handleConfirm({ value }) {
value.value = value
}
Trigger Slot
Enable use-default-slot and use the default slot to customize the picker trigger component.
<wd-picker :columns="columns" v-model="value" use-default-slot>
<wd-button>Slot Trigger</wd-button>
</wd-picker>
Attributes
| Parameter | Description | Type | Options | Default | Minimum Version |
|---|---|---|---|---|---|
| v-model | Selected value. For multi-column pickers, this should be an array. | string/number/boolean/array | - | - | - |
| columns | Picker data. Can be an array of strings or objects. If a 2D array, it becomes a multi-column picker. | array | - | - | - |
| loading | Loading state | boolean | - | false | - |
| loading-color | Loading color (hexadecimal format, no shorthand). | string | - | #4D80F0 | - |
| columns-height | Internal picker roller height | number | - | 231 | - |
| value-key | Key for the value property in option objects |
string | - | value | - |
| label-key | Key for the label property in option objects |
string | - | label | - |
| title | Popup title | string | - | - | - |
| cancel-button-text | Cancel button text | string | - | Cancel | - |
| confirm-button-text | Confirm button text | string | - | Confirm | - |
| label | Left-side text label | string | - | - | - |
| placeholder | Placeholder text | string | - | Select | - |
| disabled | Disabled state | boolean | - | false | - |
| readonly | Readonly state | boolean | - | false | - |
| display-format | Custom display text formatting function (returns a string) | function | - | - | - |
| column-change | Function to handle column changes (receives pickerView instance, selected item, column index, and resolve) | function | - | - | - |
| size | Picker size | string | large | - | - |
| label-width | Left-side label width | string | - | 33% | - |
| error | Error state (displays value in red) | boolean | - | false | - |
| required | Required field style | boolean | - | false | - |
| marker-side | Position of the required marker | 'before' | 'after' | - | 'before' | 1.12.0 |
| align-right | Right-align the picker value | boolean | - | false | - |
| use-label-slot | Use label slot | boolean | - | false | - |
| use-default-slot | Use default slot | boolean | - | false | - |
| before-confirm | Pre-confirmation validation function (receives value, resolve, picker) | function | - | - | - |
| close-on-click-modal | Close popup when clicking the mask | boolean | - | true | - |
| z-index | Popup z-index | number | - | 15 | - |
| safe-area-inset-bottom | Enable bottom safe area for iPhone X-type devices | boolean | - | true | - |
| ellipsis | Enable text overflow ellipsis | boolean | - | false | - |
| prop | Form model field name (required for form validation) | string | - | - | - |
| rules | Form validation rules (used with wd-form) |
FormItemRule [] |
- | [] |
- |
| immediate-change | Trigger picker-view change event immediately on touch release (supported in WeChat Mini Program and Alipay Mini Program from v1.2.25) | boolean | - | false | 1.2.25 |
| clearable | Show clear button | boolean | - | false | 1.11.0 |
| root-portal | Detach from page to resolve fixed positioning issues | boolean | - | false | 1.11.0 |
FormItemRule Structure
| Key | Description | Type |
|---|---|---|
| required | Whether the field is required | boolean |
| message | Error message text | string |
| validator | Custom validation function (can return a Promise for async validation) |
(value, rule) => boolean | Promise |
| pattern | Validate using a regular expression (fails if no match) | RegExp |
Events
| Event Name | Description | Parameters | Minimum Version |
|---|---|---|---|
| confirm | Triggered on confirm button click | { value, selectedItems }, where value is the selected value (array for multi-column), and selectedItems is the selected option(s) |
- |
| cancel | Triggered on cancel button click | - | - |
| open | Triggered when picker popup opens | - | - |
| clear | Triggered on clear button click | - | 1.11.0 |
Methods
| Method Name | Description | Parameters | Minimum Version |
|---|---|---|---|
| open | Open picker popup | - | - |
| close | Close picker popup | - | - |
Slots
| Name | Description | Minimum Version |
|---|---|---|
| default | Default slot content | - |
| label | Left-side label slot | - |
External Classes
| Class Name | Description | Minimum Version |
|---|---|---|
| custom-class | Root node styles | - |
| custom-view-class | Custom styles for pickerView | - |
| custom-label-class | Custom styles for label | - |
| custom-value-class | Custom styles for value | - |