mirror of
https://gitee.com/vant-contrib/vant.git
synced 2025-04-06 03:57:59 +08:00
docs(Area): using @vant/area-data (#8491)
This commit is contained in:
neverland
GitHub
parent
3451fe747b
commit
92f6a6a662
@ -61,6 +61,7 @@
|
||||
},
|
||||
"devDependencies": {
|
||||
"@vant/cli": "^3.9.2",
|
||||
"@vant/area-data": "^1.0.0",
|
||||
"@vue/compiler-sfc": "^3.0.6",
|
||||
"prettier": "2.1.0",
|
||||
"vue": "^3.0.6"
|
||||
|
||||
@ -17,9 +17,9 @@
|
||||
|
||||
<script lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { areaList } from '@vant/area-data';
|
||||
import { useTranslate } from '@demo/use-translate';
|
||||
import { Toast } from '../../toast';
|
||||
import { areaList } from '../../area/demo/area';
|
||||
|
||||
const i18n = {
|
||||
'zh-CN': {
|
||||
|
||||
@ -20,12 +20,54 @@ app.use(Area);
|
||||
|
||||
### Basic Usage
|
||||
|
||||
To initailize `Area` component, `area-list` property is required. Data structure will be introduced later.
|
||||
To initailize `Area` component, `area-list` property is required.
|
||||
|
||||
```html
|
||||
<van-area title="Title" :area-list="areaList" />
|
||||
```
|
||||
|
||||
### areaList Data Structure
|
||||
|
||||
An object contains three properties: `province_list`, `city_list` and `county_list`. Each property is a simple key-value object, key is a 6-bit code of the area of which first two bits stand for the province or state, middle two bits are used as city code and the last two are district code, value is the name of the area. If the code stands for an area that has sub-areas, lower bits of it will be filled with 0.
|
||||
|
||||
Sample data:
|
||||
|
||||
```js
|
||||
export default {
|
||||
province_list: {
|
||||
110000: 'Beijing',
|
||||
330000: 'Zhejiang Province',
|
||||
},
|
||||
city_list: {
|
||||
110100: 'Beijing City',
|
||||
330100: 'Hangzhou',
|
||||
},
|
||||
county_list: {
|
||||
110101: 'Dongcheng District',
|
||||
110102: 'Xicheng District',
|
||||
// ....
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### @vant/area-data
|
||||
|
||||
Vant officially provides a default area data, which can be imported through [@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 };
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Initial Value
|
||||
|
||||
To have a selected value，simply pass the `code` of target area to `value` property.
|
||||
@ -78,61 +120,13 @@ To have a selected value，simply pass the `code` of target area to `value` prop
|
||||
|
||||
| Event | Description | Arguments |
|
||||
| --- | --- | --- |
|
||||
| confirm | Emitted when the confirm button is clicked | selected areas |
|
||||
| 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 |
|
||||
|
||||
### Slots
|
||||
### ConfirmResult
|
||||
|
||||
| Name | Description |
|
||||
| -------------- | ---------------------------- |
|
||||
| title | Custom title |
|
||||
| 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_ | - |
|
||||
|
||||
### areaList Data Structure
|
||||
|
||||
An object contains three properties: `province_list`, `city_list` and `county_list`. Each property is a simple key-value object, key is a 6-bit code of the area of which first two bits stand for the province or state, middle two bits are used as city code and the last two are district code, value is the name of the area. If the code stands for an area that has sub-areas, lower bits of it will be filled with 0.
|
||||
|
||||
Example of `AreaList`
|
||||
|
||||
```js
|
||||
export default {
|
||||
province_list: {
|
||||
110000: 'Beijing',
|
||||
330000: 'Zhejiang Province',
|
||||
},
|
||||
city_list: {
|
||||
110100: 'Beijing City',
|
||||
330100: 'Hangzhou',
|
||||
},
|
||||
county_list: {
|
||||
110101: 'Dongcheng District',
|
||||
110102: 'Xicheng District',
|
||||
110105: 'Chaoyang District',
|
||||
110106: 'Fengtai District',
|
||||
330105: 'Gongshu District',
|
||||
330106: 'Xihu District',
|
||||
// ....
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Sample data : [Area.json](https://github.com/youzan/vant/blob/dev/src/area/demo/area-en.ts).
|
||||
|
||||
### argument of callback function confirm
|
||||
|
||||
An array contains selected area objects.
|
||||
|
||||
`code` - code of selected area, `name` - name of selected area
|
||||
An array that contains selected area objects.
|
||||
|
||||
```js
|
||||
[
|
||||
@ -150,3 +144,19 @@ An array contains selected area objects.
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
### Slots
|
||||
|
||||
| Name | Description |
|
||||
| -------------- | ---------------------------- |
|
||||
| title | Custom title |
|
||||
| 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_ | - |
|
||||
|
||||
@ -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_ | - |
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 在桌面端无法操作组件？
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -22,7 +22,7 @@
|
||||
|
||||
<script lang="ts">
|
||||
import { ref } from 'vue';
|
||||
import { areaList } from './area';
|
||||
import { areaList } from '@vant/area-data';
|
||||
import { areaListEn } from './area-en';
|
||||
import { useTranslate } from '@demo/use-translate';
|
||||
|
||||
|
||||
@ -19,9 +19,9 @@
|
||||
|
||||
<script lang="ts">
|
||||
import { reactive, toRefs } from 'vue';
|
||||
import { areaList } from '@vant/area-data';
|
||||
import { useTranslate } from '@demo/use-translate';
|
||||
import { AreaColumnOption } from '../../area';
|
||||
import { areaList } from '../../area/demo/area';
|
||||
import { areaListEn } from '../../area/demo/area-en';
|
||||
|
||||
const i18n = {
|
||||
|
||||
@ -1855,6 +1855,11 @@
|
||||
"@typescript-eslint/types" "4.6.0"
|
||||
eslint-visitor-keys "^2.0.0"
|
||||
|
||||
"@vant/area-data@^1.0.0":
|
||||
version "1.0.0"
|
||||
resolved "https://registry.npm.taobao.org/@vant/area-data/download/@vant/area-data-1.0.0.tgz#063af9ccb5ccafa333d7dc28103937501cfec671"
|
||||
integrity sha1-Bjr5zLXMr6Mz19woEDk3UBz+xnE=
|
||||
|
||||
"@vant/cli@^3.9.2":
|
||||
version "3.9.2"
|
||||
resolved "https://registry.npm.taobao.org/@vant/cli/download/@vant/cli-3.9.2.tgz#6eb7149004c8b36bc5fc08c16cc36c78bcdd3b4b"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user