docs(Area): using @vant/area-data (#8491)
This commit is contained in:
neverland
+72
-67
@@ -20,15 +20,59 @@ app.use(Area);
|
||||
|
||||
### 基础用法
|
||||
|
||||
要初始化一个 `Area` 组件，你需要传入一个 `area-list` 属性，数据格式具体可看下面数据格式章节。
|
||||
初始化省市区组件时，需要通过 `area-list` 属性传入省市区数据。
|
||||
|
||||
```html
|
||||
<van-area title="标题" :area-list="areaList" />
|
||||
```
|
||||
|
||||
### areaList 格式
|
||||
|
||||
areaList 为对象结构，包含 `province_list`、`city_list`、`county_list` 三个 key。
|
||||
|
||||
每项以地区码作为 key，省市区名字作为 value。地区码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。比如北京的地区码为 `11`，以 0 补足 6 位，为 `110000`。
|
||||
|
||||
示例数据如下：
|
||||
|
||||
```js
|
||||
const areaList = {
|
||||
province_list: {
|
||||
110000: '北京市',
|
||||
120000: '天津市',
|
||||
},
|
||||
city_list: {
|
||||
110100: '北京市',
|
||||
120100: '天津市',
|
||||
},
|
||||
county_list: {
|
||||
110101: '东城区',
|
||||
110102: '西城区',
|
||||
// ....
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### @vant/area-data
|
||||
|
||||
Vant 官方提供了一份默认的省市区数据，可以通过 [@vant/area-data](https://github.com/youzan/vant/tree/dev/packages/vant-area-data) 引入：
|
||||
|
||||
```bash
|
||||
yarn add @vant/area-data
|
||||
```
|
||||
|
||||
```ts
|
||||
import { areaList } from '@vant/area-data';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
return { areaList };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 选中省市区
|
||||
|
||||
如果想选中某个省市区，需要传入一个 `value` 属性，绑定对应的省市区 `code`。
|
||||
如果想选中某个省市区，需要传入一个 `value` 属性，绑定对应的地区码。
|
||||
|
||||
```html
|
||||
<van-area title="标题" :area-list="areaList" value="110101" />
|
||||
@@ -60,7 +104,7 @@ app.use(Area);
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| value | 当前选中的省市区`code` | _string_ | - |
|
||||
| value | 当前选中项对应的地区码 | _string_ | - |
|
||||
| title | 顶部栏标题 | _string_ | - |
|
||||
| confirm-button-text | 确认按钮文字 | _string_ | `确认` |
|
||||
| cancel-button-text | 取消按钮文字 | _string_ | `取消` |
|
||||
@@ -71,75 +115,20 @@ app.use(Area);
|
||||
| item-height | 选项高度，支持 `px` `vw` `vh` `rem` 单位，默认 `px` | _number \| string_ | `44` |
|
||||
| columns-num | 显示列数，3-省市区，2-省市，1-省 | _number \| string_ | `3` |
|
||||
| visible-item-count | 可见的选项个数 | _number \| string_ | `6` |
|
||||
| swipe-duration | 快速滑动时惯性滚动的时长，单位`ms` | _number \| string_ | `1000` |
|
||||
| is-oversea-code | 根据`code`校验海外地址，海外地址会划分至单独的分类 | _() => boolean_ | - |
|
||||
| swipe-duration | 快速滑动时惯性滚动的时长，单位 `ms` | _number \| string_ | `1000` |
|
||||
| is-oversea-code | 根据地区码校验海外地址，海外地址会划分至单独的分类 | _() => boolean_ | - |
|
||||
|
||||
### Events
|
||||
|
||||
| 事件 | 说明 | 回调参数 |
|
||||
| ------- | ------------------ | ---------------------------------------- |
|
||||
| confirm | 点击右上方完成按钮 | 一个数组参数，具体格式看下方数据格式章节 |
|
||||
| cancel | 点击取消按钮时 | - |
|
||||
| change | 选项改变时触发 | 所有列选中值，当前列对应的索引 |
|
||||
| 事件 | 说明 | 回调参数 |
|
||||
| ------- | ------------------ | ------------------------------ |
|
||||
| confirm | 点击右上方完成按钮 | _result: ConfirmResult_ |
|
||||
| cancel | 点击取消按钮时 | - |
|
||||
| change | 选项改变时触发 | 所有列选中值，当前列对应的索引 |
|
||||
|
||||
### Slots
|
||||
### ConfirmResult 格式
|
||||
|
||||
| 名称 | 说明 |
|
||||
| -------------- | ------------------ |
|
||||
| title | 自定义标题内容 |
|
||||
| columns-top | 自定义选项上方内容 |
|
||||
| columns-bottom | 自定义选项下方内容 |
|
||||
|
||||
### 方法
|
||||
|
||||
通过 ref 可以获取到 Area 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
|
||||
|
||||
| 方法名 | 说明 | 参数 | 返回值 |
|
||||
| --- | --- | --- | --- |
|
||||
| reset | 根据 code 重置所有选项，若不传 code，则重置到第一项 | _code?: string_ | - |
|
||||
|
||||
### 省市区列表数据格式
|
||||
|
||||
整体是一个 object，包含 `province_list`, `city_list`, `county_list` 三个 key。
|
||||
|
||||
每项以省市区编码作为 key，省市区名字作为 value。编码为 6 位数字，前两位代表省份，中间两位代表城市，后两位代表区县，以 0 补足 6 位。如北京编码为 `11`，以零补足 6 位，为 `110000`。
|
||||
|
||||
`AreaList`具体格式如下：
|
||||
|
||||
```js
|
||||
export default {
|
||||
province_list: {
|
||||
110000: '北京市',
|
||||
120000: '天津市',
|
||||
},
|
||||
city_list: {
|
||||
110100: '北京市',
|
||||
110200: '县',
|
||||
120100: '天津市',
|
||||
120200: '县',
|
||||
},
|
||||
county_list: {
|
||||
110101: '东城区',
|
||||
110102: '西城区',
|
||||
110105: '朝阳区',
|
||||
110106: '丰台区',
|
||||
120101: '和平区',
|
||||
120102: '河东区',
|
||||
120103: '河西区',
|
||||
120104: '南开区',
|
||||
120105: '河北区',
|
||||
// ....
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
完整示例数据见 [Area.json](https://github.com/youzan/vant/blob/dev/src/area/demo/area.ts)。
|
||||
|
||||
### 点击完成时返回的数据格式
|
||||
|
||||
返回的数据整体为一个数组，数组内包含 `columnsNum` 个数据， 每个数据对应一列选项中被选中的数据。
|
||||
|
||||
`code` 代表被选中的地区编码， `name` 代表被选中的地区名称
|
||||
confirm 事件返回的数据整体为一个数组，数组每一项对应一列选项中被选中的数据。
|
||||
|
||||
```js
|
||||
[
|
||||
@@ -158,6 +147,22 @@ export default {
|
||||
];
|
||||
```
|
||||
|
||||
### Slots
|
||||
|
||||
| 名称 | 说明 |
|
||||
| -------------- | ------------------ |
|
||||
| title | 自定义标题内容 |
|
||||
| columns-top | 自定义选项上方内容 |
|
||||
| columns-bottom | 自定义选项下方内容 |
|
||||
|
||||
### 方法
|
||||
|
||||
通过 ref 可以获取到 Area 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
|
||||
|
||||
| 方法名 | 说明 | 参数 | 返回值 |
|
||||
| --- | --- | --- | --- |
|
||||
| reset | 根据地区码重置所有选项，若不传地区码，则重置到第一项 | _code?: string_ | - |
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 在桌面端无法操作组件？
|
||||
|
||||
Reference in New Issue
Block a user