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');
-
+
-
+