From a9baa3b2d188a16637acc1051fb554142408315b Mon Sep 17 00:00:00 2001 From: chenjiahan Date: Fri, 21 Jan 2022 11:03:48 +0800 Subject: [PATCH] docs(Area): update documents --- .../docs/markdown/migrate-from-v3.zh-CN.md | 22 ++++++- packages/vant/src/area/README.md | 55 ++++++----------- packages/vant/src/area/README.zh-CN.md | 61 +++++++------------ packages/vant/src/area/demo/index.vue | 8 +-- 4 files changed, 63 insertions(+), 83 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 e96736244..f36489e60 100644 --- a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md +++ b/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md @@ -13,17 +13,35 @@ - columns 数据格式定义不合理，容易产生误解 - 数据流不清晰，暴露了过多的实例方法来对数据进行操作 -为了解决上述问题，我们在 v4 版本中对 Picker 组件进行了重构（同时也影响 Area 和 DatetimePicker 组件）。 +为了解决上述问题，我们在 v4 版本中对 Picker 组件进行了重构。 #### 主要变更 - 支持通过 `v-model` 绑定当前选中的值，移除 `default-index` 属性 - 重新定义了 `columns` 属性的结构 -- 移除了所有操作内部数据的实例方法 +- 移除了操作内部数据的实例方法，仅保留 `confirm` 方法 - 调整了 `confirm`、`cancel`、`change` 事件的参数 - 重命名 `item-height` 属性为 `option-height` - 重命名 `visible-item-count` 属性为 `visible-option-num` +详细用法请参见 [Picker 组件文档](#/zh-CN/picker)。 + +### Area 组件重构 + +Area 组件是基于 Picker 组件进行封装的，因此本次升级也对 Area 组件进行了内部逻辑的重构，并优化了部分 API 设计。 + +#### 主要变更 + +- 支持通过 `v-model` 绑定当前选中的值 +- 移除 `reset` 方法，现在可以通过修改 `v-model` 来进行重置 +- 移除 `is-oversea-code` 属性 +- 调整所有事件的参数，与 Picker 组件保持一致 +- 重命名 `value` 属性我 `modelValue` +- 重命名 `item-height` 属性为 `option-height` +- 重命名 `visible-item-count` 属性为 `visible-option-num` + +详细用法请参见 [Area 组件文档](#/zh-CN/area)。 + ### 其他 API 调整 4.0 版本中，以下 API 进行了不兼容更新： diff --git a/packages/vant/src/area/README.md b/packages/vant/src/area/README.md index 0fab4506d..9917787d9 100644 --- a/packages/vant/src/area/README.md +++ b/packages/vant/src/area/README.md @@ -75,12 +75,23 @@ export default { }; ``` -### Initial Value +### Model Value -To have a selected value，simply pass the `code` of target area to `value` property. +Bind the currently selected area code via `v-model`. ```html - + +``` + +```js +import { ref } from 'vue'; + +export default { + setup() { + const value = ref('330302'); + return { value }; + }, +}; ``` ### Columns Number @@ -109,7 +120,7 @@ To have a selected value，simply pass the `code` of target area to `value` prop | Attribute | Description | Type | Default | | --- | --- | --- | --- | -| value | the `code` of selected area | _string_ | - | +| v-model | the `code` of selected area | _string_ | - | | title | Toolbar title | _string_ | - | | confirm-button-text | Text of confirm button | _string_ | `Confirm` | | cancel-button-text | Text of cancel button | _string_ | `Cancel` | @@ -121,36 +132,14 @@ To have a selected value，simply pass the `code` of target area to `value` prop | columns-num | Level of picker | _number \| string_ | `3` | | visible-option-num | Count of visible columns | _number \| string_ | `6` | | swipe-duration | Duration of the momentum animation，unit `ms` | _number \| string_ | `1000` | -| is-oversea-code | The method to validate oversea code | _() => boolean_ | - | ### Events | Event | Description | Arguments | | --- | --- | --- | -| confirm | Emitted when the confirm button is clicked | _result: ConfirmResult_ | -| cancel | Emitted when the cancel button is clicked | - | -| change | Emitted when current option changed | current values，column index | - -### ConfirmResult - -An array that contains selected area objects. - -```js -[ - { - code: '330000', - name: 'Zhejiang Province', - }, - { - code: '330100', - name: 'Hangzhou', - }, - { - code: '330105', - name: 'Xihu District', - }, -]; -``` +| confirm | Emitted when the confirm button is clicked | _{ selectedValues, selectedOptions }_ | +| cancel | Emitted when the cancel button is clicked | _{ selectedValues, selectedOptions }_ | +| change | Emitted when current option is changed | _{ selectedValues, selectedOptions, columnIndex }_ | ### Slots @@ -163,14 +152,6 @@ An array that contains selected area objects. | columns-top | Custom content above columns | - | | columns-bottom | Custom content below columns | - | -### Methods - -Use [ref](https://v3.vuejs.org/guide/component-template-refs.html) to get Area instance and call instance methods. - -| Name | Description | Attribute | Return value | -| ----- | ------------------------- | --------------- | ------------ | -| reset | Reset all options by code | _code?: string_ | - | - ### Types The component exports the following type definitions: diff --git a/packages/vant/src/area/README.zh-CN.md b/packages/vant/src/area/README.zh-CN.md index 5d085a16a..6357014ec 100644 --- a/packages/vant/src/area/README.zh-CN.md +++ b/packages/vant/src/area/README.zh-CN.md @@ -77,12 +77,23 @@ export default { }; ``` -### 选中省市区 +### 控制选中项 -如果想选中某个省市区，需要传入一个 `value` 属性，绑定对应的地区码。 +通过 `v-model` 绑定当前选中的地区码。 ```html - + +``` + +```js +import { ref } from 'vue'; + +export default { + setup() { + const value = ref('330302'); + return { value }; + }, +}; ``` ### 配置显示列 @@ -111,7 +122,7 @@ export default { | 参数 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | -| value | 当前选中项对应的地区码 | _string_ | - | +| v-model | 当前选中项对应的地区码 | _string_ | - | | title | 顶部栏标题 | _string_ | - | | confirm-button-text | 确认按钮文字 | _string_ | `确认` | | cancel-button-text | 取消按钮文字 | _string_ | `取消` | @@ -123,36 +134,14 @@ export default { | columns-num | 显示列数，3-省市区，2-省市，1-省 | _number \| string_ | `3` | | visible-option-num | 可见的选项个数 | _number \| string_ | `6` | | swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` | -| is-oversea-code | 根据地区码校验海外地址，海外地址会划分至单独的分类 | _() => boolean_ | - | ### Events -| 事件 | 说明 | 回调参数 | -| ------- | ------------------ | ------------------------------ | -| confirm | 点击完成按钮时触发 | _result: ConfirmResult_ | -| cancel | 点击取消按钮时触发 | - | -| change | 选项改变时触发 | 所有列选中值，当前列对应的索引 | - -### ConfirmResult 格式 - -confirm 事件返回的数据整体为一个数组，数组每一项对应一列选项中被选中的数据。 - -```js -[ - { - code: '110000', - name: '北京市', - }, - { - code: '110100', - name: '北京市', - }, - { - code: '110101', - name: '东城区', - }, -]; -``` +| 事件 | 说明 | 回调参数 | +| --- | --- | --- | +| confirm | 点击完成按钮时触发 | _{ selectedValues, selectedOptions }_ | +| cancel | 点击取消按钮时触发 | _{ selectedValues, selectedOptions }_ | +| change | 选项改变时触发 | _{ selectedValues, selectedOptions, columnIndex }_ | ### Slots @@ -165,20 +154,12 @@ confirm 事件返回的数据整体为一个数组，数组每一项对应一列 | columns-top | 自定义选项上方内容 | - | | columns-bottom | 自定义选项下方内容 | - | -### 方法 - -通过 ref 可以获取到 Area 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。 - -| 方法名 | 说明 | 参数 | 返回值 | -| --- | --- | --- | --- | -| reset | 根据地区码重置所有选项，若不传地区码，则重置到第一项 | _code?: string_ | - | - ### 类型定义 组件导出以下类型定义： ```ts -import type { AreaProps, AreaList, AreaInstance, AreaColumnOption } from 'vant'; +import type { AreaProps, AreaList, AreaInstance } from 'vant'; ``` `AreaInstance` 是组件实例的类型，用法如下： diff --git a/packages/vant/src/area/demo/index.vue b/packages/vant/src/area/demo/index.vue index e6ff04c57..6c9c7b6ac 100644 --- a/packages/vant/src/area/demo/index.vue +++ b/packages/vant/src/area/demo/index.vue @@ -7,14 +7,14 @@ import { useTranslate } from '../../../docs/site/use-translate'; const t = useTranslate({ 'zh-CN': { - title2: '选中省市区', + title2: '控制选中项', title3: '配置显示列', title4: '配置列占位提示文字', columnsPlaceholder: ['请选择', '请选择', '请选择'], areaList, }, 'en-US': { - title2: 'Initial Value', + title2: 'Model Value', title3: 'Columns Number', title4: 'Columns Placeholder', columnsPlaceholder: ['Choose', 'Choose', 'Choose'], @@ -27,11 +27,11 @@ const value = ref('330302');