@qisen/zh-address-parse

中国大陆收货地址智能解析。纯 TypeScript 编写，核心零运行时依赖，行政区划数据以独立文件引入。

安装

npm i @qisen/zh-address-parse -S

使用方法

ESM / TypeScript

import AddressParse, { createParser } from '@qisen/zh-address-parse'
import areaData from '@qisen/zh-address-parse/area'
// 街道数据体积较大，按需引入；引入后自动开启街道级解析
import streetData from '@qisen/zh-address-parse/street'

// 注册全局默认数据
AddressParse.use(areaData, streetData)

const result = AddressParse('广东省深圳市南山区粤海街道科技园南路1号 张三 13800138000')

不希望使用全局注册时，用 createParser 创建互相隔离的解析函数：

import { createParser } from '@qisen/zh-address-parse'
import areaData from '@qisen/zh-address-parse/area'

const parse = createParser(areaData)
parse('北京市海淀区中关村大街1号')

CommonJS

const AddressParse = require('@qisen/zh-address-parse')
const areaData = require('@qisen/zh-address-parse/area')

AddressParse.use(areaData)
const result = AddressParse('上海市浦东新区世纪大道100号')

script 标签

浏览器版本已内置省市区三级数据，无需再注册。

<script src="https://unpkg.com/@qisen/zh-address-parse/dist/zh-address-parse.global.js"></script>
<script>
  const result = window.ZhAddressParse('浙江省杭州市余杭区文一西路969号 李四 13900139000')
  console.log(result)
</script>

API

AddressParse(address[, options])

返回解析结果对象。

| 字段 | 说明 | 类型 | |--------------|---------------------------------|--------| | province | 省 / 自治区 / 直辖市 | string | | city | 市（直辖市回填同名；省直辖县级市如济源市为空，其本身落在 area） | string | | area | 区 / 县 / 县级市（东莞等直筒子市为镇 / 街道，地址未写街道时为市名） | string | | street | 街道 / 镇 / 乡（需引入街道数据；直筒子市已提升至 area） | string | | detail | 详细地址 | string | | name | 收件人姓名 | string | | phone | 手机号或固话（已去除分隔符） | string | | postalCode | 邮编 | string | | provinceCode | 省级 12 位区划码 | string | | cityCode | 市级 12 位区划码 | string | | areaCode | 区县级 12 位区划码 | string | | streetCode | 街道级 12 位区划码 | string |

options

| 参数名 | 说明 | 类型 | 默认值 | |----------------|--------------------------------|-----------------|-----------| | area | 本次解析使用的省市区数据，优先级高于全局注册 | AreaData | - | | street | 本次解析使用的街道数据 | StreetData | - | | extraGovData | 追加的自定义区划，仅对本次解析生效，不会污染全局 | ExtraGovData | - | | textFilter | 解析前需要剔除的关键词 | string[] | [] | | nameMaxLength | 姓名最大长度 | number | 4 | | parseStreet | 是否解析街道级 | boolean | 有街道数据时开启 |

type AreaData = { v: string; p: string; c: string; a: string }
type StreetData = { v: string; s: string }
type GovData = { code: string; name: string; provinceCode?: string; cityCode?: string }
type ExtraGovData = {
  province?: GovData[]
  city?: GovData[]
  area?: GovData[]
  street?: GovData[]
}

AddressParse.use(areaData[, streetData])

注册全局默认数据。重复调用会整体替换，不会累加。

createParser(areaData[, streetData])

返回一个持有独立数据的解析函数，不读写全局状态，适合多数据源并存的服务端场景。

AddressParse.dataVersion()

返回当前已注册数据的日期版本。

Demo

仓库 demo/ 目录带两个可直接运行的示例（不随 npm 包发布）：

• demo/index.html：浏览器交互页，npm run build 后直接用浏览器打开，粘贴地址实时解析；
• demo/node.mjs：Node 端示例，npm run demo 运行，含街道四级解析、createParser 与 extraGovData。

import AddressParse from '@qisen/zh-address-parse'
import areaData from '@qisen/zh-address-parse/area'

AddressParse.use(areaData)

const samples = [
  '北京市朝阳区望京街道阜通东大街6号院3号楼 张三 13800138000',
  '广东省深圳市南山区科技园南路1号 李四 13900139000 518000',
  '广东深圳南山科技园路1号',
  '海淀区中关村大街1号',
  '河南省济源市济水街道xx路1号',
  '内蒙古呼和浩特市新城区中山路1号',
  '广东省广州市天河区天河路100号201房王五',
  '收件人：赵六 联系电话：010-88886666 地址：浙江省杭州市余杭区文一西路969号 邮编：311121',
]

for (const text of samples) {
  console.log(text, '=>', AddressParse(text))
}

带自定义过滤词与追加区划：

AddressParse('電話13800138000 聯系人张三 广东省深圳市虚拟区科技园路1号', {
  textFilter: ['電話', '聯系人'],
  extraGovData: {
    area: [{ code: '999999', name: '虚拟区', cityCode: '4403' }],
  },
})
// => { province: '广东省', city: '深圳市', area: '虚拟区', areaCode: '999999000000',
//      detail: '科技园路1号', name: '张三', phone: '13800138000', ... }
// 不传 extraGovData 时，「虚拟区」无法识别，会原样留在 detail 里

浏览器端实时解析：

<textarea id="addressContent"></textarea>
<ul id="result"></ul>

<script src="./dist/zh-address-parse.global.js"></script>
<script>
  const input = document.getElementById('addressContent')
  const output = document.getElementById('result')

  input.addEventListener('input', (e) => {
    const parsed = window.ZhAddressParse(e.target.value)
    output.innerHTML = Object.entries(parsed)
      .map(([key, value]) => `<li>${key}：${value}</li>`)
      .join('')
  })
</script>

更新国家地理信息

数据来自民政部行政区划代码接口 https://dmfw.mca.gov.cn/interface.html，可随时重新拉取：

# 仅更新省 / 市 / 区县三级
npm run update:area

# 同时更新街道四级（约 2800 次请求，已内置限流与重试）
npm run update:street

# 作为依赖方，通过 bin 直接更新到自己的目录
npx zh-address-parse-update --with-street --out ./src/data

可用参数：--with-street、--out <dir>、--concurrency <n>、--throttle <ms>、--retry <n>、--timeout <ms>、--help。