blackteay/vant
1
0
Fork 0
mirror of https://gitee.com/vant-contrib/vant.git synced 2025-04-06 03:57:59 +08:00
Code Issues Projects Releases Wiki Activity

docs(Picker): new document

Browse Source
This commit is contained in:
chenjiahan 2022-01-19 14:26:57 +08:00 committed by neverland
parent d16075f39e
commit cc10eb1f2a
5 changed files with 222 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
packages/vant/docs/markdown/migrate-from-v3.zh-CN.md
View File

@ -17,6 +17,7 @@
#### 主要变更
- 支持通过 `v-model` 绑定当前选中的值，移除 `default-index` 属性
- 重新定义了 `columns` 属性的结构
- 移除了所有操作内部数据的实例方法
- 调整了 `confirm`、`cancel`、`change` 事件的参数

1
packages/vant/src/picker/Picker.tsx
View File

@ -61,7 +61,6 @@ export const pickerSharedProps = {
const pickerProps = extend({}, pickerSharedProps, {
columns: makeArrayProp<PickerColumn | PickerColumn[]>(),
modelValue: makeArrayProp<number | string>(),
defaultIndex: makeNumericProp(0),
toolbarPosition: makeStringProp<PickerToolbarPosition>('top'),
columnsFieldNames: Object as PropType<PickerFieldNames>,
});

242
packages/vant/src/picker/README.md
View File

@ -42,11 +42,11 @@ export default {
{ text: 'Indiana', value: 'Indiana' },
{ text: 'Maine', value: 'Maine' },
];
const onConfirm = (option, index) => {
Toast(`Value: ${option.value}, Index: ${index}`);
const onConfirm = ({ selectedValues }) => {
Toast(`Value: ${selectedValues.join(',')}`);
};
const onChange = (option, index) => {
Toast(`Value: ${option.value}, Index: ${index}`);
const onChange = ({ selectedValues }) => {
Toast(`Value: ${selectedValues.join(',')}`);
};
const onCancel = () => Toast('Cancel');
@ -60,6 +60,57 @@ export default {
};
```
### With Popup
```html
<van-field
v-model="result"
is-link
readonly
label="City"
placeholder="Choose City"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
title="Title"
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
```
```js
import { ref } from 'vue';
export default {
setup() {
const columns = [
{ text: 'Delaware', value: 'Delaware' },
{ text: 'Florida', value: 'Florida' },
{ text: 'Georqia', value: 'Georqia' },
{ text: 'Indiana', value: 'Indiana' },
{ text: 'Maine', value: 'Maine' },
];
const result = ref('');
const showPicker = ref(false);
const onConfirm = ({ selectedOptions }) => {
showPicker.value = false;
fieldValue.value = selectedOptions[0].text;
};
return {
result,
columns,
onConfirm,
showPicker,
};
},
};
```
### Multiple Columns
```html
@ -101,27 +152,45 @@ export default {
const columns = [
{
text: 'Zhejiang',
value: 'Zhejiang',
children: [
{
text: 'Hangzhou',
children: [{ text: 'Xihu' }, { text: 'Yuhang' }],
value: 'Hangzhou',
children: [
{ text: 'Xihu', value: 'Xihu' },
{ text: 'Yuhang', value: 'Yuhang' },
],
},
{
text: 'Wenzhou',
children: [{ text: 'Lucheng' }, { text: 'Ouhai' }],
value: 'Wenzhou',
children: [
{ text: 'Lucheng', value: 'Lucheng' },
{ text: 'Ouhai', value: 'Ouhai' },
],
},
],
},
{
text: 'Fujian',
value: 'Fujian',
children: [
{
text: 'Fuzhou',
children: [{ text: 'Gulou' }, { text: 'Taijiang' }],
value: 'Fuzhou',
children: [
{ text: 'Gulou', value: 'Gulou' },
{ text: 'Taijiang', value: 'Taijiang' },
],
},
{
text: 'Xiamen',
children: [{ text: 'Siming' }, { text: 'Haicang' }],
value: 'Xiamen',
children: [
{ text: 'Siming', value: 'Siming' },
{ text: 'Haicang', value: 'Haicang' },
],
},
],
},
@ -142,51 +211,15 @@ export default {
export default {
setup() {
const columns = [
{ text: 'Delaware', disabled: true },
{ text: 'Florida' },
{ text: 'Georqia' },
{ text: 'Delaware', value: 'Delaware', disabled: true },
{ text: 'Florida', value: 'Florida' },
{ text: 'Georqia', value: 'Georqia' },
];
return { columns };
},
};
```
### Set Column Values
```html
<van-picker ref="picker" title="Title" :columns="columns" @change="onChange" />
```
```js
import { ref } from 'vue';
export default {
setup() {
const picker = ref(null);
const states = {
Group1: ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'],
Group2: ['Alabama', 'Kansas', 'Louisiana', 'Texas'],
};
const columns = [
{ values: Object.keys(states) },
{ values: states.Group1 },
];
const onChange = (values) => {
picker.value.setColumnValues(1, states[values[0]]);
};
return {
picker,
columns,
onChange,
};
},
};
```
### Loading
When Picker columns data is acquired asynchronously, use `loading` prop to show loading prompt.
@ -204,7 +237,7 @@ export default {
const loading = ref(true);
setTimeout(() => {
columns.value = ['Option'];
columns.value = [{ text: 'Option', value: 'option' }];
loading.value = false;
}, 1000);
@ -213,51 +246,6 @@ export default {
};
```
### With Popup
```html
<van-field
v-model="result"
is-link
readonly
label="City"
placeholder="Choose City"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
title="Title"
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
```
```js
import { ref } from 'vue';
export default {
setup() {
const columns = ['Delaware', 'Florida', 'Georqia', 'Indiana', 'Maine'];
const result = ref('');
const showPicker = ref(false);
const onConfirm = (value) => {
result.value = value;
showPicker.value = false;
};
return {
result,
columns,
onConfirm,
showPicker,
};
},
};
```
### Custom Columns Field
```html
@ -302,6 +290,7 @@ export default {
const customFieldName = {
text: 'cityName',
value: 'cityName',
children: 'cities',
};
@ -319,8 +308,8 @@ export default {
| Attribute | Description | Type | Default |
| --- | --- | --- | --- |
| columns | Columns data | _Column[]_ | `[]` |
| columns-field-names | custom columns field | _object_ | `{ text: 'text', values: 'values', children: 'children' }` |
| columns | Columns data | _PickerOption[] \| PickerOption[][]_ | `[]` |
| columns-field-names | custom columns field | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
| title | Toolbar title | _string_ | - |
| confirm-button-text | Text of confirm button | _string_ | `Confirm` |
| cancel-button-text | Text of cancel button | _string_ | `Cancel` |
@ -328,59 +317,47 @@ export default {
| loading | Whether to show loading prompt | _boolean_ | `false` |
| show-toolbar | Whether to show toolbar | _boolean_ | `true` |
| allow-html | Whether to allow HTML in option text | _boolean_ | `false` |
| default-index | Default value index of single column picker | _number \| string_ | `0` |
| option-height | Option height, supports `px` `vw` `vh` `rem` unit, default `px` | _number \| string_ | `44` |
| visible-option-num | Count of visible columns | _number \| string_ | `6` |
| swipe-duration | Duration of the momentum animation，unit `ms` | _number \| string_ | `1000` |
### Events
Picker events will pass different parameters according to the columns are single or multiple
| Event | Description | Arguments |
| --- | --- | --- |
| confirm | Emitted when click confirm button | Single column：current value，current index<br>Multiple columns：current values，current indexes |
| cancel | Emitted when click cancel button | Single column：current value，current index<br>Multiple columns：current values，current indexes |
| change | Emitted when current option changed | Single column：Picker instance, current value，current index<br>Multiple columns：Picker instance, current values，column index |
| confirm | Emitted when click confirm button | _{ selectedValues, selectedOptions }_ |
| cancel | Emitted when click cancel button | _{ selectedValues, selectedOptions }_ |
| change | Emitted when current option changed | _{ selectedValues, selectedOptions, columnIndex }_ |
### Slots
| Name | Description | SlotProps |
| --------------- | ---------------------------- | -------------------------- |
| toolbar `3.1.2` | Custom toolbar content | - |
| title | Custom title | - |
| confirm | Custom confirm button text | - |
| cancel | Custom cancel button text | - |
| option | Custom option content | _option: string \| object_ |
| columns-top | Custom content above columns | - |
| columns-bottom | Custom content below columns | - |
| Name | Description | SlotProps |
| --------------- | ---------------------------- | ---------------------- |
| toolbar `3.1.2` | Custom toolbar content | - |
| title | Custom title | - |
| confirm | Custom confirm button text | - |
| cancel | Custom cancel button text | - |
| option | Custom option content | _option: PickerOption_ |
| columns-top | Custom content above columns | - |
| columns-bottom | Custom content below columns | - |
### Data Structure of Column
### Data Structure of PickerOption
| Key | Description | Type |
| ------------ | ------------------------- | --------------------------- |
| values | Value of column | _Array<string \| number>_ |
| defaultIndex | Default value index | _number_ |
| className | ClassName for this column | _string \| Array \| object_ |
| children | Cascade children | _Column_ |
| Key | Description | Type |
| --------- | ------------------------- | --------------------------- |
| text | Text | _string \| number_ |
| value | Value of option | _string \| number_ |
| disabled | Whether to disable option | _boolean_ |
| children | Cascade children options | _PickerOption[]_ |
| className | ClassName for this option | _string \| Array \| object_ |
### Methods
Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Picker instance and call instance methods.
| Name | Description | Attribute | Return value |
| --- | --- | --- | --- |
| getValues | Get current values of all columns | - | values |
| setValues | Set current values of all columns | values | - |
| getIndexes | Get current indexes of all columns | - | indexes |
| setIndexes | Set current indexes of all columns | indexes | - |
| getColumnValue | Get current value of the column | columnIndex | value |
| setColumnValue | Set current value of the column | columnIndex, value | - |
| getColumnIndex | Get current index of the column | columnIndex | optionIndex |
| setColumnIndex | Set current index of the column | columnIndex, optionIndex | - |
| getColumnValues | Get columns data of the column | columnIndex | values |
| setColumnValues | Set columns data of the column | columnIndex, values | - |
| confirm | Stop scrolling and emit confirm event | - | - |
| Name | Description | Attribute | Return value |
| ------- | ------------------------------------- | --------- | ------------ |
| confirm | Stop scrolling and emit confirm event | - | - |
### Types
@ -393,9 +370,10 @@ import type {
PickerOption,
PickerInstance,
PickerFieldNames,
PickerObjectColumn,
PickerObjectOption,
PickerToolbarPosition,
PickerCancelEventParams,
PickerChangeEventParams,
PickerConfirmEventParams,
} from 'vant';
```

251
packages/vant/src/picker/README.zh-CN.md
View File

@ -49,15 +49,12 @@ export default {
{ text: '温州', value: 'Wenzhou' },
{ text: '绍兴', value: 'Shaoxing' },
{ text: '湖州', value: 'Huzhou' },
{ text: '嘉兴', value: 'Jiaxing' },
{ text: '金华', value: 'Jinhua' },
{ text: '衢州', value: 'Quzhou' },
];
const onConfirm = (option, index) => {
Toast(`当前值: ${option.value}, 当前索引: ${index}`);
const onConfirm = ({ selectedValues }) => {
Toast(`当前值: ${selectedValues.join(',')}`);
};
const onChange = (option, index) => {
Toast(`当前值: ${option.value}, 当前索引: ${index}`);
const onChange = ({ selectedValues }) => {
Toast(`当前值: ${selectedValues.join(',')}`);
};
const onCancel = () => Toast('取消');
@ -71,6 +68,58 @@ export default {
};
```
### 搭配弹出层使用
在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
```html
<van-field
v-model="value"
is-link
readonly
label="城市"
placeholder="选择城市"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
```
```js
import { ref } from 'vue';
export default {
setup() {
const columns = [
{ text: '杭州', value: 'Hangzhou' },
{ text: '宁波', value: 'Ningbo' },
{ text: '温州', value: 'Wenzhou' },
{ text: '绍兴', value: 'Shaoxing' },
{ text: '湖州', value: 'Huzhou' },
];
const result = ref('');
const showPicker = ref(false);
const onConfirm = ({ selectedOptions }) => {
showPicker.value = false;
fieldValue.value = selectedOptions[0].text;
};
return {
result,
columns,
onConfirm,
showPicker,
};
},
};
```
### 多列选择
`columns` 属性可以通过二维数组的形式配置多列选择。
@ -118,27 +167,45 @@ export default {
const columns = [
{
text: '浙江',
value: 'Zhejiang',
children: [
{
text: '杭州',
children: [{ text: '西湖区' }, { text: '余杭区' }],
value: 'Hangzhou',
children: [
{ text: '西湖区', value: 'Xihu' },
{ text: '余杭区', value: 'Yuhang' },
],
},
{
text: '温州',
children: [{ text: '鹿城区' }, { text: '瓯海区' }],
value: 'Wenzhou',
children: [
{ text: '鹿城区', value: 'Lucheng' },
{ text: '瓯海区', value: 'Ouhai' },
],
},
],
},
{
text: '福建',
value: 'Fujian',
children: [
{
text: '福州',
children: [{ text: '鼓楼区' }, { text: '台江区' }],
value: 'Fuzhou',
children: [
{ text: '鼓楼区', value: 'Gulou' },
{ text: '台江区', value: 'Taijiang' },
],
},
{
text: '厦门',
children: [{ text: '思明区' }, { text: '海沧区' }],
value: 'Xiamen',
children: [
{ text: '思明区', value: 'Siming' },
{ text: '海沧区', value: 'Haicang' },
],
},
],
},
@ -163,53 +230,15 @@ export default {
export default {
setup() {
const columns = [
{ text: '杭州', disabled: true },
{ text: '宁波' },
{ text: '温州' },
{ text: '杭州', value: 'Hangzhou', disabled: true },
{ text: '宁波', value: 'Ningbo' },
{ text: '温州', value: 'Wenzhou' },
];
return { columns };
},
};
```
### 动态设置选项
通过 Picker 上的实例方法可以更灵活地控制选择器，比如使用 `setColumnValues` 方法实现多列联动。
```html
<van-picker ref="picker" :columns="columns" @change="onChange" />
```
```js
import { ref } from 'vue';
export default {
setup() {
const picker = ref(null);
const cities = {
浙江: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
福建: ['福州', '厦门', '莆田', '三明', '泉州'],
};
const columns = [
{ values: Object.keys(cities) },
{ values: cities['浙江'] },
];
const onChange = (values) => {
picker.value.setColumnValues(1, cities[values[0]]);
};
return {
picker,
columns,
onChange,
};
},
};
```
### 加载状态
若选择器数据是异步获取的，可以通过 `loading` 属性显示加载提示。
@ -227,7 +256,7 @@ export default {
const loading = ref(true);
setTimeout(() => {
columns.value = ['选项'];
columns.value = [{ text: '选项', value: 'option' }];
loading.value = false;
}, 1000);
@ -236,52 +265,6 @@ export default {
};
```
### 搭配弹出层使用
在实际场景中，Picker 通常作为用于辅助表单填写，可以搭配 Popup 和 Field 实现该效果。
```html
<van-field
v-model="value"
is-link
readonly
label="城市"
placeholder="选择城市"
@click="showPicker = true"
/>
<van-popup v-model:show="showPicker" round position="bottom">
<van-picker
:columns="columns"
@cancel="showPicker = false"
@confirm="onConfirm"
/>
</van-popup>
```
```js
import { ref } from 'vue';
export default {
setup() {
const columns = ['杭州', '宁波', '温州', '绍兴', '湖州', '嘉兴', '金华'];
const result = ref('');
const showPicker = ref(false);
const onConfirm = (value) => {
result.value = value;
showPicker.value = false;
};
return {
result,
columns,
onConfirm,
showPicker,
};
},
};
```
### 自定义 Columns 的结构
```html
@ -326,6 +309,7 @@ export default {
const customFieldName = {
text: 'cityName',
value: 'cityName',
children: 'cities',
};
@ -343,8 +327,8 @@ export default {
| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| columns | 对象数组，配置每一列显示的数据 | _Column[]_ | `[]` |
| columns-field-names | 自定义 `columns` 结构中的字段 | _object_ | `{ text: 'text', values: 'values', children: 'children' }` |
| columns | 对象数组，配置每一列显示的数据 | _PickerOption[] \| PickerOption[][]_ | `[]` |
| columns-field-names | 自定义 `columns` 结构中的字段 | _object_ | `{ text: 'text', value: 'value', children: 'children' }` |
| title | 顶部栏标题 | _string_ | - |
| confirm-button-text | 确认按钮文字 | _string_ | `确认` |
| cancel-button-text | 取消按钮文字 | _string_ | `取消` |
@ -352,61 +336,47 @@ export default {
| loading | 是否显示加载状态 | _boolean_ | `false` |
| show-toolbar | 是否显示顶部栏 | _boolean_ | `true` |
| allow-html | 是否允许选项内容中渲染 HTML | _boolean_ | `false` |
| default-index | 单列选择时，默认选中项的索引 | _number \| string_ | `0` |
| option-height | 选项高度，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `44` |
| visible-option-num | 可见的选项个数 | _number \| string_ | `6` |
| swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` |
### Events
当选择器有多列时，事件回调参数会返回数组。
| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| confirm | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，所有列选中值对应的索引 |
| change | 选项改变时触发 | 单列：选中值，选中值对应的索引<br>多列：所有列选中值，当前列对应的索引 |
| confirm | 点击完成按钮时触发 | _{ selectedValues, selectedOptions }_ |
| cancel | 点击取消按钮时触发 | _{ selectedValues, selectedOptions }_ |
| change | 选项改变时触发 | _{ selectedValues, selectedOptions, columnIndex }_ |
### Slots
| 名称 | 说明 | 参数 |
| ---------------- | ---------------------- | -------------------------- |
| toolbar `v3.1.2` | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | _option: string \| object_ |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
| 名称 | 说明 | 参数 |
| ---------------- | ---------------------- | ---------------------- |
| toolbar `v3.1.2` | 自定义整个顶部栏的内容 | - |
| title | 自定义标题内容 | - |
| confirm | 自定义确认按钮内容 | - |
| cancel | 自定义取消按钮内容 | - |
| option | 自定义选项内容 | _option: PickerOption_ |
| columns-top | 自定义选项上方内容 | - |
| columns-bottom | 自定义选项下方内容 | - |
### Column 数据结构
### PickerOption 数据结构
当传入多列数据时，`columns` 为一个对象数组，数组中的每一个对象配置每一列，每一列有以下 `key`:
| 键名 | 说明 | 类型 |
| ------------ | -------------------------- | --------------------------- |
| values | 列中对应的备选值 | _Array<string \| number>_ |
| defaultIndex | 初始选中项的索引，默认为 0 | _number_ |
| className | 为对应列添加额外的类名 | _string \| Array \| object_ |
| children | 级联选项 | _Column_ |
| 键名 | 说明 | 类型 |
| --------- | ------------ | --------------------------- |
| text | 选项文字内容 | _string \| number_ |
| value | 选项对应的值 | _string \| number_ |
| disabled | 是否禁用选项 | _boolean_ |
| children | 级联选项 | _PickerOption[]_ |
| className | 选项额外类名 | _string \| Array \| object_ |
### 方法
通过 ref 可以获取到 Picker 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
| 方法名 | 说明 | 参数 | 返回值 |
| --- | --- | --- | --- |
| getValues | 获取所有列选中的值 | - | values |
| setValues | 设置所有列选中的值 | values | - |
| getIndexes | 获取所有列选中值对应的索引 | - | indexes |
| setIndexes | 设置所有列选中值对应的索引 | indexes | - |
| getColumnValue | 获取对应列选中的值 | columnIndex | value |
| setColumnValue | 设置对应列选中的值 | columnIndex, value | - |
| getColumnIndex | 获取对应列选中项的索引 | columnIndex | optionIndex |
| setColumnIndex | 设置对应列选中项的索引 | columnIndex, optionIndex | - |
| getColumnValues | 获取对应列中所有选项 | columnIndex | values |
| setColumnValues | 设置对应列中所有选项 | columnIndex, values | - |
| confirm | 停止惯性滚动并触发 confirm 事件 | - | - |
| 方法名 | 说明 | 参数 | 返回值 |
| ------- | --------------------------------- | ---- | ------ |
| confirm | 停止惯性滚动并触发 `confirm` 事件 | - | - |
### 类型定义
@ -419,9 +389,10 @@ import type {
PickerOption,
PickerInstance,
PickerFieldNames,
PickerObjectColumn,
PickerObjectOption,
PickerToolbarPosition,
PickerCancelEventParams,
PickerChangeEventParams,
PickerConfirmEventParams,
} from 'vant';
```

3
packages/vant/src/picker/demo/data.ts
View File

@ -5,9 +5,6 @@ export const basicColumns = {
{ text: '温州', value: 'Wenzhou' },
{ text: '绍兴', value: 'Shaoxing' },
{ text: '湖州', value: 'Huzhou' },
{ text: '嘉兴', value: 'Jiaxing' },
{ text: '金华', value: 'Jinhua' },
{ text: '衢州', value: 'Quzhou' },
],
'en-US': [
{ text: 'Delaware', value: 'Delaware' },