> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# zxkv-area 省市区数据

省市区数据插件：[**zxkv-area**](https://www.npmjs.com/package/zxkv-area)「👈 点击查看」

## 「业务需求」

在项目开发过程中，总会遇到各种各样的场景和业务需求，此时就需要前端和后端进行协商处理。比如：提交一个地区数据时，最初设想是采用后端提供封装处理好的 **省/市/区** 数据来进行 API 的查询。此时，前端的功能逻辑无非就是看下具体的场景需求来和后端开发同事协商 API 接口返回的数据格式。按照以往的经验，无非就一下几种情况：

#### 方案一（一次性返回，数据量大，需前端自己处理数据）：

- 需要返回一个包含 父子层级 **“省/市/区”** 嵌套好的 **JSON** 数据集合「后端同事称作**集合**，前端同事常称作**数组对象**」；

#### 方案二（多次请求，单次返回数据量比方式一少很多）：

- 首次返回 **Level 1「省」** 级别的数据，然后依据选择的省的 **“province_code”** 来获取 **Level2「市」** 级别的数据列表，以此类推，通过点击 **Level2「市」** 级别数据，点击获取对应的 **“city_code”** 来通过后端的 API 来获取 **Level3「区」** 的数据集合进行数据展示；

#### 方案三（前端存储数据，无需请求后端接口）：

- 前端与后端协商好一组省市区对应 **code** 码的数据，将处理好的 **JSON 数据** 保存在前端，通过封装处理自己想要的数据格式；按照后端所需数据格式方式提交数据即可；

## 「方案评审」

当前现状：时间紧，任务重，功能优化，需要高效快速开发；要求：又快又好实现目前的方案；经过探讨，最终采用上述“**方案三**”的形式来进行功能模块的开发。与后端协商好，将数据放在前端处理，就准备着手梳理需求进行功能开发了。

因为是 **Web 端**、**H5 端**和**小程序端**都需要用到这组数据，**小程序**和**H5 端**采用了 **VantUI**进行开发，同时有看到 **VantUI**组件库里有**省市区数据连联动的组件**，相对这两端来说，有现成的组件使用，开发起来还是比较快的，但是 **Web 端** 需要使用数据，最终为了保持三端数据一致，就采用了 移动端的 **VantUI** 地区联动组件的数据。

## 「实现过程」

H5 端和 小程序端 都是采用的 UI 组件库自带的地区选择组件进行开发的，相对 Web 端来说，开发起来比较省时省力；但是 PC Web 端 就没这么好运了，找来找去，就借用了 移动端 UI 组件库开源的地区数据进行了开发。

- 「好处」：快速实现了功能的开发迭代；
- 「弊端」：数据结构单一，只有单独的省、市、区的数据，数据量大，没有组合，需要自己便利数据进行数据过滤和整合；

为了便于后续功能迭代需要地区数据时，不再受到数据的影响，决定封装一个“省市区”三级数据的数据包。方便后续开发时在项目中使用。

## 「使用说明」

#### 安装


```sh [npm]
npm install zxkv-area
```

```sh [yarn]
yarn add zxkv-area
```

```sh [pnpm]
pnpm add zxkv-area
```

```sh [bun]
bun add zxkv-area
```

```sh [deno]
deno add npm:zxkv-area
```

#### 案例

处理生成的数据分为两类，分别是对 Object 对象类型和 Array 数组对象类型；

#### 导出方法 - Array

```js title="集合数据"
import { province_list, city_list, district_list } from "zxkv-area";
```

#### Array 数据格式

| **方法**        | **介绍** |
| ------------- | ------ |
| province_list | 省数据    |
| city_list     | 市数据    |
| district_list | 区数据    |

#### 「省 - level1」：province_list

```json title="省数据：province_list"
[
	{
		parent:"0",
		name:"北京市",
		code:"110000"
	},
	......
]
```

#### 「市 - level2」：city_list

```json title="市数据：city_list"
[
	{
		parent:"110000",
		name:"北京市",
		code:"110100"
	},
	......
]
```

#### 「区 - level3」：district_list

```json title="区数据：district_list"
[
	{
		parent:"110100",
		name:"东城区",
		code:"110101"
	},
	......
]
```

#### 导出方法 - Object

```js title="对象数据"
import { province_data, city_data, district_data } from "zxkv-area";
```

#### Object 数据格式

| **方法**        | **介绍** |
| ------------- | ------ |
| province_data | 省数据    |
| city_data     | 市数据    |
| district_data | 区数据    |

#### 「省 - level1」：province_data

```json title="省数据：province_data"
{
  110000: "北京市",
  120000: "天津市",
  ......
}
```

#### 「市 - level2」：city_data

```json title="市数据：city_data"
{
	110100: "北京市",
	......
}
```

#### 「区 - level3」：district_data

```json title="区数据：district_data"
{
	110101: "东城区",
	......
}
```

#### Tree 结构数据

```js title="Tree 结构数据"
import { area_lv2, area_lv3 } from "zxkv-area";
```

| **方法**   | **介绍**  |
| -------- | ------- |
| area_lv2 | 省-市两级   |
| area_lv3 | 省-市-区三级 |

#### 「省 - 市」两级数据结构

```json title="省市两级 Tree 数据"
[
  {
    parent:" 0",
    name:"北京市",
    code:"110000",
    children:[
      {
        parent:"110000",
        name:"北京市",
        code:"110100"
      },
      ......
    ]
  },
  ......
]
```

#### 「省 - 市 - 区」三级数据结构

```json title="省市区三级 Tree 数据"
[
  {
    parent:" 0",
    name:"北京市",
    code:"110000",
    children:[
      {
        parent:"110000",
        name:"北京市",
        code:"110100",
        children:[
        {
        parent:"110100",
        name:" 东城区",
        code:"110101"
      },
      ......
    ]
  },
  ......
]
  },
  ......
]
```

### 「数据连接」

> - [**全国省市区数据**](https://area.site/china)
> - [**全球国家地区数据**](https://area.site/world)

## 「总结反思」

通过本次对地区数据的封装，可以依据场景和业务需求引用自己所需的数据格式；本次主要分享包的使用，希望对大家有所帮助。有好的建议或意见可以留言。