react-native-address-parse HarmonyOS 适配文档

中国地址解析鸿蒙插件：解析寄件地址中的省/市/区/详址/姓名/电话/邮编，内置最新行政区划数据，供 RNOH (React Native OpenHarmony) 项目使用。

下载安装

| 资料来源 | 地址 | |---------|------| | AtomGit | https://atomgit.com/oh-react-native/react-native-address-parse |

npm install react-native-address-parse

目录结构

├── src/NativeAddressParse.ts       # codegen TurboModule spec
├── index.tsx                       # JS 入口
├── index.d.ts                      # 类型声明
├── harmony/
│   ├── address_parse/              # ArkTS 模块源码
│   │   ├── src/main/ets/
│   │   │   ├── AddressParseTurboModule.ets   # 核心解析实现（内置行政区划数据）
│   │   │   └── AddressParsePackage.ets       # Package 注册
│   │   ├── src/main/cpp/
│   │   │   └── ReactNativeAddressParsePackage.h/.cpp  # C++ 胶水层
│   │   └── oh-package.json5
│   └── react_native_address_parse.har  # 预构建 HAR 产物
└── package.json                    # 含 harmony.autolinking 配置

兼容性说明

| 项目 | 说明 | |------|------| | RNOH 版本 | 0.84.x | | HarmonyOS / OpenHarmony | API 12+ (modelVersion 26.0.0) | | 架构 | Fabric + TurboModule (New Architecture) |

使用方法

与原库 API 完全一致：

import parseAddress from 'react-native-address-parse';

const result = await parseAddress('浙江省杭州市西湖区文三路138号张三 13812345678');
// {
//   province: '浙江省', provinceCode: '33',
//   city: '杭州市',     cityCode: '3301',
//   area: '西湖区',     areaCode: '330106',
//   detail: '文三路138号',
//   name: '张三', phone: '13812345678', postalCode: ''
// }

可选参数：

parseAddress(address, {
  type: 0,              // 0: 正常模式（默认），1: 补充政府区划数据模式
  textFilter: [],       // 需过滤的关键词
  nameMaxLength: 0,     // 姓名最大长度限制，0 表示不限制
  extraGovData: { province: [], city: [], area: [] },  // 自定义行政区划数据
});

接入方式（宿主工程）

1. npm install react-native-address-parse 后，在 harmony/oh-package.json5 与 harmony/entry/oh-package.json5 添加：

"dependencies": {
  "@rnoh/react-native-address-parse--address_parse": "file:../node_modules/react-native-address-parse/harmony/react_native_address_parse.har",
}

2. 重新执行 ohpm install，autolinking 会自动生成 RNOHPackagesFactory.ets / autolinking.cmake 并链接 C++ Package（类名 ReactNativeAddressParsePackage）。

3. JS 侧重新打包 bundle（npx react-native bundle-harmony）并构建 HAP。

实现说明与注意事项

• 地址解析、行政区划匹配均在 ArkTS 侧同步完成，JS 侧通过 TurboModule parse 方法调用；内置数据：34 省（含港澳台）/ 392 市 / 3209 区县。
• 行政区划数据出处：AreaCity-JsSpider-StatsGov 2025.251231.260403 版（2026-04-03 采集，含重庆两江新区等最新变更）。该数据聚合自 国家地名信息库（2025-12-31，2026 年起民政部/统计局不再另行公布区划代码，此为官方权威渠道）、腾讯地图行政区划 v20251119、高德地图行政区域。数据转换脚本生成的 .ets 文件头部亦标注了出处，请勿手工编辑。
• C++ 胶水层需在 ArkTSTurboModule 子类构造函数中声明 methodMap_（ARK_METHOD_METADATA(parse, 5)），否则 TM 注册成功但 JS 调用会报 "undefined is not a function"。
• package.json 的 harmony.autolinking.ohPackageName 为 @rnoh/react-native-address-parse；宿主 oh-package 的依赖 key 需带 HAR 模块名后缀（--address_parse）。
• 升级 HAR 后若报 "Cannot find module"，删除 harmony/entry/src/main/ets/RNOHPackagesFactory.ets 与两级 oh-package-lock.json5 后重装。

遗留问题

• 无。

开源协议

本项目基于 The MIT License (MIT) 开源，作者：坚果 (jianguoxu)，请自由地享受和参与开源。