docs(Area): update documents

2025-04-06 03:57:59 +08:00 · 2022-01-21 11:03:48 +08:00 · 2022-01-21 11:03:48 +08:00 · a9baa3b2d1
commit a9baa3b2d1
parent 0186219586
4 changed files with 63 additions and 83 deletions
--- 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 进行了不兼容更新：
--- 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
-<van-area title="Title" :area-list="areaList" value="110101" />
+<van-area v-model="value" title="Title" :area-list="areaList" />
+```
+
+```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:
--- 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
-<van-area title="标题" :area-list="areaList" value="110101" />
+<van-area v-model="value" title="标题" :area-list="areaList" />
+```
+
+```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` 是组件实例的类型，用法如下：
--- 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');

 <template>
  <demo-block card :title="t('basicUsage')">
-    <van-area v-model="value" :title="t('title')" :area-list="t('areaList')" />
+    <van-area :title="t('title')" :area-list="t('areaList')" />
  </demo-block>

  <demo-block card :title="t('title2')">
-    <van-area :title="t('title')" :area-list="t('areaList')" :value="value" />
+    <van-area v-model="value" :title="t('title')" :area-list="t('areaList')" />
  </demo-block>

  <demo-block card :title="t('title3')">