antd-mini
Version:
antd-mini 是支付宝小程序 UI 组件库，遵循 Ant Design 规范。
396 lines (351 loc) • 38.2 kB
Markdown
nav:
path: /components
group:
title: Information Entry
order: 10
toc: 'content'
supportPlatform: ['alipay', 'wechat']
# Picker
The Picker selector displays a scrollable list of one or more collections of options, providing consistency between the iOS and Android-side experiences compared to native pickers.
- One or more sets of association options are provided for selection by the user.
- When there are less than 5 options, it is recommended to tile the options directly. Using Radio is a better choice.
## Introduction
In `index.json` Introducing Components in
```json
"usingComponents": {
#if ALIPAY
"ant-picker": "antd-mini/es/Picker/index",
"ant-cascader-picker": "antd-mini/es/Picker/CascaderPicker/index"
#endif
#if WECHAT
"ant-picker": "antd-mini/Picker/index",
"ant-cascader-picker": "antd-mini/Picker/CascaderPicker/index"
#endif
}
```
## Code Sample
### Basic use
```xml
<ant-picker
placeholder="请选择"
title="请选择"
emptyText="暂无数据"
defaultValue="{{defaultValue}}"
options="{{list}}"
#if ALIPAY
onCancel="handleDismiss"
onVisibleChange="handleTriggerPicker"
onOk="handleOk"
onChange="handleChange"
#endif
#if WECHAT
bindcancel="handleDismiss"
bindvisiblechange="handleTriggerPicker"
bindok="handleOk"
bindchange="handleChange"
#endif
/>
```
```js
Page({
data: {
defaultValue: '上海',
list: ['北京', '上海', '深圳', '广州', '南京', '武汉', '无锡', '苏州'],
},
handleDismiss(e) {
console.log('onCancel', e);
},
handleTriggerPicker(visible, e) {
console.log('onVisibleChange', visible, e);
},
handleOk(value, column, e) {
console.log('onOk value', value, 'onOk column', column, e);
},
handleChange(value, column, e) {
console.log('onChange value', value, 'onChange column', column, e);
},
});
```
### Format selected text
> `onFormat` The function return value is the value of the selected area to be rendered.
```xml
<ant-picker
#if ALIPAY
onFormat="onFormat"
#endif
#if WECHAT
onFormat="{{onFormat}}"
#endif
/>
```
```js
Page({
data: {
#if WECHAT
onFormat: (value) => {
return `已选择：${value}`;
},
#endif
},
#if ALIPAY
onFormat: (value) => {
return `已选择：${value}`;
},
#endif
})
```
### multi-column selection
> When complex options appear, but do not need to link between options, you can achieve multi-column selection in the following ways:
```xml
<ant-picker
defaultValue="{{['Tues', 'pm']}}"
options="{{columns}}"
#if ALIPAY
onFormat="formatTime"
#endif
#if WECHAT
onFormat="{{formatTime}}"
bindok="handleOk"
#endif
/>
```
```js
Page({
data: {
columns: [
[
{
label: '周一',
value: 'Mon',
},
{
label: '周二',
value: 'Tues',
},
{
label: '周三',
value: 'Wed',
},
{
label: '周四',
value: 'Thur',
},
{
label: '周五',
value: 'Fri',
},
],
[
{
label: '上午',
value: 'am',
},
{
label: '下午',
value: 'pm',
},
],
],
#if WECHAT
formatTime: (value) => {
return column.map((c) => c && c.label).join('，');
},
#endif
},
#if ALIPAY
formatTime: (value) => {
return column.map((c) => c && c.label).join('，');
}
#endif
})
```
### Controlled Mode
> `value` property and `ok` Events, with the implementation of controlled mode.
```xml
<ant-picker
value="{{value}}"
options="{{list}}"
#if ALIPAY
onOk="handleControlledOk"
#endif
#if WECHAT
bindok="handleControlledOk"
#endif
/>
<ant-button onTap="handleChangeControlled">Select Shenzhen</ant-button>
<ant-button onTap="handleClearControlled">Empty</ant-button>
```
```js
Page({
data:{
value: '上海',
list: ['北京', '上海', '深圳', '广州', '南京', '武汉', '无锡', '苏州'],
},
handleControlledOk(value) {
#if ALIPAY
this.setData({
value,
});
#endif
#if WECHAT
this.setData({
value: value.detail[0],
});
#endif
},
handleClearControlled() {
this.setData({
value: '',
});
},
handleChangeControlled() {
this.setData({
value: '深圳',
});
},
})
```
### Cascading Picker
> When more complex options appear, the need for linkage between options requires the introduction `ant-cascader-picker` Cascade selection components to achieve. The component implements the cascading function by passing in the following tree structure:
```xml
<ant-cascader-picker
options="{{cityList}}"
/>
```
```js
Page({
data: {
cityList: [
{
label: '北京',
value: '11',
children: [
{
label: '北京',
value: '110',
},
],
},
{
label: '河北',
value: '18',
children: [
{
label: '石家庄',
value: '188',
},
{
label: '唐山',
value: '181',
},
],
},
],
},
});
```
### Demo Code
<code src='../../demo/pages/Picker/index'></code>
## API
### Picker
| Property | Description | Type | Default Value |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| animationType | Animation type, optional`transform` `position`, the default is used`transform`Animation performance is better. Due to a bug in the basic library of small programs, the picker-view shadow style in the pop-up window may have style problems under iOS and can be temporarily switched`position`Solve | string | `transform` |
| className | Class Name | string | - |
| defaultValue | Default Value | string \| number \| Array\<string \| number\> | - |
| disabled | Disable | boolean | false |
| readonly | Read-only | boolean | false |
| cancelText | Cancel Copy | string | 'Cancel' |
| content | Custom Content Slots | slot | - |
| indicatorStyle | Check Box Style | string | - |
| indicatorClassName | Class name of the check box | string | - |
| maskClassName | Class name of the layer | string | - |
| maskClosable | Click whether the layer can be closed | boolean | true |
| maskStyle | Mask Style | string | - |
| okText | Confirm Button Copy | string | 'OK' |
| emptyText | Empty status button copy | string | 'No data' |
| options | picker data, configure options for each column | [PickerColumnItem](#pickercolumnitem)[] | [] |
| placeholder | Prompt Copy | string | 'Please Select' |
| popClassName | Popup box class name | string | - |
| popStyle | Pop-up Style | string | - |
| prefix | Prefix | slot | - |
| style | Style | string | - |
| suffix | Suffix | slot | - |
| title | Pop-up Title | string \| slot | - |
| value | Selected value | string \| number \| Array\<string \| number\> | - |
| visible | Display | boolean | false |
| defaultVisible | Display by default | boolean | false |
| onFormat | Text display format of the selected value | (value: [PickerColumnItem](#pickercolumnitem), column: [PickerColumnItem](#pickercolumnitem)) => string | - |
| #if ALIPAY onOk | Click the OK button to trigger the callback | (value: [PickerColumnItem](#pickercolumnitem), column: [PickerColumnItem](#pickercolumnitem), event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onCancel | Click the cancel button/layer to trigger the callback | (event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onChange | The selected item changes, triggering a callback | (value: [PickerColumnItem](#pickercolumnitem), column: [PickerColumnItem](#pickercolumnitem), event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onVisibleChange | Pop-up display/hide status change trigger | (visible: boolean, event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindok | Click the OK button to trigger the callback | (value: [PickerColumnItem](#pickercolumnitem), column: [PickerColumnItem](#pickercolumnitem), event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindcancel | Click the cancel button/layer to trigger the callback | (event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindchange | The selected item changes, triggering a callback | (value: [PickerColumnItem](#pickercolumnitem), column: [PickerColumnItem](#pickercolumnitem), event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindvisiblechange | Pop-up display/hide status change trigger | (visible: boolean, event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
### CascaderPicker
| Property | Description | Type | Default Value |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| animationType | Animation type, optional`transform` `position`, the default is used`transform`Animation performance is better. Due to a bug in the basic library of small programs, the picker-view shadow style in the pop-up window may have style problems under iOS and can be temporarily switched`position`Solve | string | `transform` |
| className | Class Name | string | - |
| defaultValue | Default selected value | string[] | - |
| disabled | Disable | boolean | false |
| readonly | Read-only | boolean | false |
| cancelText | Cancel Copy | string | 'Cancel' |
| content | Custom Content Slots | slot | - |
| format | Time format display, the format is the same[dayjs](https://day.js.org/docs/zh-CN/display/format) | string | 'YYYY/MM/DD' |
| indicatorStyle | Check Box Style | string | - |
| indicatorClassName | Class name of the check box | string | - |
| maskClassName | Class name of the layer | string | - |
| maskClosable | Click whether the layer can be closed | boolean | true |
| maskStyle | Mask Style | string | - |
| okText | Confirm Button Copy | string | 'OK' |
| options | Optional data | [CascaderOption](#cascaderoption)[] | [] |
| placeholder | Prompt Copy | string | 'Please Select' |
| popClassName | Popup box class name | string | - |
| popStyle | Pop-up Style | string | - |
| prefix | Prefix | slot | - |
| style | Style | string | - |
| suffix | Suffix | slot | - |
| title | Pop-up Title | string \| slot | - |
| value | Selected value | string[] | - |
| visible | Display | boolean | false |
| defaultVisible | Display by default | boolean | false |
| onFormat | The text display format of the selected value. The default display is labels.join(''). | (value: string[], selectedOptions: [CascaderOption](#cascaderoption)[]) => string | - |
| #if ALIPAY onOk | Click the OK button to trigger the callback | (value: string[], selectedOptions: [CascaderOption](#cascaderoption)[], event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onCancel | Click the cancel button/layer to trigger the callback | (event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onChange | The selected item changes, triggering a callback | (value: string[], selectedOptions: [CascaderOption](#cascaderoption)[], event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if ALIPAY onVisibleChange | Pop-up display/hide status change trigger | (visible: boolean, event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindok | Click the OK button to trigger the callback | (value: string[], selectedOptions: [CascaderOption](#cascaderoption)[], event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindcancel | Click the cancel button/layer to trigger the callback | (event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindchange | The selected item changes, triggering a callback | (value: string[], selectedOptions: [CascaderOption](#cascaderoption)[], event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
| #if WECHAT bindvisibleChange | Pop-up display/hide status change trigger | (visible: boolean, event: [Event](https://opendocs.alipay.com/mini/framework/event-object)) => void | - |
### PickerColumnItem
| Parameters | Description | Type | Default Value |
| ----- | ---- | ---------------- | ------ |
| label | Text | string | - |
| value | Value | string \| number | - |
### CascaderOption
| Parameters | Description | Type | Default Value |
| -------- | ---- | ---------------- | ------ |
| label | Text | string | - |
| value | Value | string \| number | - |
| children | Sub Level | CascaderOption[] | - |
### Theme customization
#### Style Variables
Component provides the following CSS variables, which can be used to customize styles. For details, see ConfigProvider Components.
| Variable name | Light Mode Default | Dark Mode Default | Remarks |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| --picker-item-color | <div style="width: 150px; height: 40px; background-color: #333333; color: #ffffff;">#333333</div> | <div style="width: 150px; height: 40px; background-color: #c5cad1; color: #ffffff;">#c5cad1</div> | Selector item color |
| --picker-header-action-color | <div style="width: 150px; height: 40px; background-color: #1677ff; color: #ffffff;">#1677ff</div> | <div style="width: 150px; height: 40px; background-color: #3086ff; color: #ffffff;">#3086ff</div> | Selector Head Operation Color |
| --picker-placeholder-color | <div style="width: 150px; height: 40px; background-color: #cccccc; color: #333333;">#cccccc</div> | <div style="width: 150px; height: 40px; background-color: #474747; color: #ffffff;">#474747</div> | Selector Placeholder Color |
| --picker-header-color | <div style="width: 150px; height: 40px; background-color: #eeeeee; color: #333333;">#eeeeee</div> | <div style="width: 150px; height: 40px; background-color: #2b2b2b; color: #ffffff;">#2b2b2b</div> | Selector head color |
| --picker-content-background-color | <div style="width: 150px; height: 40px; background-color: #ffffff; color: #333333;">#ffffff</div> | <div style="width: 150px; height: 40px; background-color: #1a1a1a; color: #ffffff;">#1a1a1a</div> | Selector Content Background Color |
| --picker-mask-bg-faded-95 | <div style="width: 150px; height: 40px; background-color: rgba(255, 255, 255, 0.05); color: #000000;">rgba(255, 255, 255, 0.05)</div> | <div style="width: 150px; height: 40px; background-color: rgba(255, 255, 255, 0.05); color: #000000;">rgba(255, 255, 255, 0.02)</div> | Selector mask background color (95% transparency) |
| --picker-mask-bg-faded-60 | <div style="width: 150px; height: 40px; background-color: rgba(255, 255, 255, 0.4); color: #000000;">rgba(255, 255, 255, 0.4)</div> | <div style="width: 150px; height: 40px; background-color: rgba(255, 255, 255, 0.4); color: #000000;">rgba(255, 255, 255, 0.01)</div> | Selector mask background color (60% transparency) |
## FAQ
### Exhibit exception when dynamically changing the number of picker columns
Due to the limitation of native picker-view, dynamic change of the number of columns is not supported for the time being.