From cc10eb1f2adddc5a6d34336669b85a8a571c1803 Mon Sep 17 00:00:00 2001 From: chenjiahan Date: Wed, 19 Jan 2022 14:26:57 +0800 Subject: [PATCH] docs(Picker): new document --- .../docs/markdown/migrate-from-v3.zh-CN.md | 1 + packages/vant/src/picker/Picker.tsx | 1 - packages/vant/src/picker/README.md | 242 ++++++++--------- packages/vant/src/picker/README.zh-CN.md | 251 ++++++++---------- packages/vant/src/picker/demo/data.ts | 3 - 5 files changed, 222 insertions(+), 276 deletions(-) diff --git a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md b/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md index 29f2a3963..e96736244 100644 --- a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md +++ b/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md @@ -17,6 +17,7 @@ #### 主要变更 +- 支持通过 `v-model` 绑定当前选中的值，移除 `default-index` 属性 - 重新定义了 `columns` 属性的结构 - 移除了所有操作内部数据的实例方法 - 调整了 `confirm`、`cancel`、`change` 事件的参数 diff --git a/packages/vant/src/picker/Picker.tsx b/packages/vant/src/picker/Picker.tsx index a0e606114..7f7574260 100644 --- a/packages/vant/src/picker/Picker.tsx +++ b/packages/vant/src/picker/Picker.tsx @@ -61,7 +61,6 @@ export const pickerSharedProps = { const pickerProps = extend({}, pickerSharedProps, { columns: makeArrayProp(), modelValue: makeArrayProp(), - defaultIndex: makeNumericProp(0), toolbarPosition: makeStringProp('top'), columnsFieldNames: Object as PropType, }); diff --git a/packages/vant/src/picker/README.md b/packages/vant/src/picker/README.md index c14a0da58..cff22077b 100644 --- a/packages/vant/src/picker/README.md +++ b/packages/vant/src/picker/README.md @@ -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 + + + + +``` + +```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 - -``` - -```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 - - - - -``` - -```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
Multiple columns：current values，current indexes | -| cancel | Emitted when click cancel button | Single column：current value，current index
Multiple columns：current values，current indexes | -| change | Emitted when current option changed | Single column：Picker instance, current value，current index
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_ | -| 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'; ``` diff --git a/packages/vant/src/picker/README.zh-CN.md b/packages/vant/src/picker/README.zh-CN.md index 187a7ab29..e38f16927 100644 --- a/packages/vant/src/picker/README.zh-CN.md +++ b/packages/vant/src/picker/README.zh-CN.md @@ -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 + + + + +``` + +```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 - -``` - -```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 - - - - -``` - -```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 | 点击完成按钮时触发 | 单列：选中值，选中值对应的索引
多列：所有列选中值，所有列选中值对应的索引 | -| cancel | 点击取消按钮时触发 | 单列：选中值，选中值对应的索引
多列：所有列选中值，所有列选中值对应的索引 | -| change | 选项改变时触发 | 单列：选中值，选中值对应的索引
多列：所有列选中值，当前列对应的索引 | +| 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_ | -| 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'; ``` diff --git a/packages/vant/src/picker/demo/data.ts b/packages/vant/src/picker/demo/data.ts index 24caf3de9..f89e1e72b 100644 --- a/packages/vant/src/picker/demo/data.ts +++ b/packages/vant/src/picker/demo/data.ts @@ -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' },