# @aurouscia/china-areas 中文文档

规范地址：https://npmcn.com/package/%40aurouscia/china-areas/

版本：0\.7\.0
npm 元数据更新时间：2026-05-18T18:52:31.845Z
中文译文更新时间：2026-11-07T05:31:30.184Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aurouscia/china-areas
原文对照：https://npmcn.com/package/%40aurouscia/china-areas/?lang=original
源码仓库：https://gitee.com/au114514/au-npm-pkgs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：886 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-05-10T16:54:53.153Z
- 最新版本发布：2026-05-18T18:52:31.713Z
- 近 30 天下载量：2573（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 1 个）

## 中文简介

2026中国行政区划(精确到区县)及工具函数

## 安装

```sh
npm install @aurouscia/china-areas
```

也可以使用：`pnpm add @aurouscia/china-areas`、`yarn add @aurouscia/china-areas`、`bun add @aurouscia/china-areas`

## README

# 中国大陆地区行政区划数据

## 数据来源

[中国国家地名信息库](https://dmfw.mca.gov.cn/) 官方开放API，精确到区县，本包发布时间即为数据更新时间

## 安装

```sh
npm install @aurouscia/china-areas
pnpm add @aurouscia/china-areas
```

## 数据结构约定

-   直辖市下的市、区、县（例如`上海市-静安区`），均为该直辖市的直接子级（没有中间的“虚拟地级”）
-   省直辖县（例如`湖北省-仙桃市`），均为所属省的直接子级（没有中间的“虚拟地级”）
-   缺少港澳台地区的数据（仅有省级元素，没有子级）

## json使用

`/dist/json`目录下为json文件，有扁平的和树状结构的两种版本，两种版本各有一个`.min.json`压缩版。

-   扁平版本
    -   `code`为六位行政区划代码
    -   `name`为行政区划名称
-   树状版本：若有子级，则有`children`属性为子级数组，否则没有`children`属性。
-   压缩版：重命名了属性`code -> c`，`name -> n`，`children -> d`，且没有空格和换行符。

## js/ts使用

本包的默认导出对象，即为所有行政区划的数组（扁平的，无树状结构）

```ts
import areas from '@aurouscia/china-areas'
```

其中每个元素均有两个属性：

-   `code`为六位行政区划代码
-   `name`为行政区划名称 如果使用ts，可引入该元素的类型定义：

```ts
import { Division } from '@aurouscia/china-areas'
```

如果需要树状结构，可以使用下文介绍的工具函数。

### 工具函数

```ts
import { xxxx } from '@aurouscia/china-areas'
```

#### getTopDivisions

获取所有的顶级行政区划，即省、直辖市、自治区

#### getDivisionChildren

获取指定行政区划代码的所有子级行政区划（错误的或没有子级的会返回空数组） 第二个参数为是否严格匹配（默认为`false`，即允许有错误）否则会在代码不存在时抛出异常。

#### getDivisionParent

获取指定行政区划代码的父级行政区划（错误的或没有父级的会返回undefined） 第二个参数为是否严格匹配（默认为`false`，即允许有错误）否则会在代码不存在时抛出异常。

#### matchDivisionByCode, matchDivisionByNames

根据行政区划六位代码或名称查找行政区划。  
第一个参数为名称数组/代码字符串，第二个参数为是否严格匹配（默认为`false`，即允许有错误）。

-   名称：字符串数组，例如`['湖北省','武汉市','江岸区']`。
    -   如果是一般的省-市-区三级，则数组长度最多为3
    -   如果是直辖市、省直辖县、直筒子市，则数组长度最多为2
    -   如果是港澳台地区，则数组长度最多为1
    -   会从高到底匹配，如果某一级没有匹配项，则只会返回到其上一级，例如`['湖北省','武昌区']`会返回`[{name:'湖北省',code:'420000'}]`，**严格匹配时会抛出异常**。
-   代码：六位字符串，例如`'420102'`。
    -   如果匹配失败，则会返回空数组
    -   如果代码长度不是六位，则会返回空数组
    -   会从高到低匹配，如果某一级没有匹配项，则只会返回到其上一级，例如`'428802'`会返回`[{name:'湖北省',code:'420000'}]`，**严格匹配时会抛出异常**。
-   返回值（如果没有抛出异常）：从高到低的区划对象数组
    -   长度为3：`[{省}, {市}, {区}]`
    -   长度为2：`[{省}, {市/省直辖县}]` 或 `[{直辖市}, {区}]`
    -   长度为1：`[{省}]`
    -   长度为0：匹配失败

#### isFinalDivision

判断指定行政区划代码是否为最终级行政区划（即没有子级）

#### isExistingCode

判断指定行政区划代码（任意级别均可）是否存在

## 原版数据

raw数据在`/dist/raw`下，通过 `npm run updateSource` 脚本从 API 获取并生成

## 源码

源代码中不包含数据，只包含生成器，如果需要：

1.  运行`npm run updateSource` 从 API 获取最新数据并生成 `source.txt`（必须）
2.  运行`npm run genTs`生成包含数据的代码（必须）
3.  运行`npm run genJson`生成json文件
4.  运行`npm test`运行单元测试
5.  运行`npm run build`打包

## 发现错误/过期

如果发现错误或过期，请在gitee上提issue，我会及时更新  
[https://gitee.com/au114514/au-npm-pkgs](https://gitee.com/au114514/au-npm-pkgs)

## 许可证

MIT

## 常见问题

### @aurouscia/china-areas 是什么？

2026中国行政区划\(精确到区县\)及工具函数

### 如何安装 @aurouscia/china-areas？

在项目目录运行 npm install @aurouscia/china-areas，或使用 pnpm add / yarn add / bun add。

### @aurouscia/china-areas 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aurouscia/china-areas 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aurouscia/china-areas 可以商用吗？

@aurouscia/china-areas 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aurouscia/china-areas 的下载量有多少？

根据 npm 官方下载统计，@aurouscia/china-areas 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,573 次，日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aurouscia/china-areas 还在维护吗？

最新版本 0\.7\.0 发布于 2026/05/19（5 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/05/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。