react-native-address-parse 1.1.0

package/README.OpenHarmony.md

@@ -0,0 +1,85 @@
+# react-native-address-parse HarmonyOS Adaptation
+
+English | [简体中文](./README.OpenHarmony_CN.md)
+
+HarmonyOS/OpenHarmony adaptation of [zh-address-parse](https://github.com/zhaocjcc/zh-address-parse): parse Chinese delivery addresses (province/city/area/detail/name/phone/postalCode).
+
+## Directory Structure
+
+```text
+├── src/NativeAddressParse.ts       # codegen TurboModule spec
+├── index.tsx                       # JS entry
+├── index.d.ts                      # type declarations
+├── harmony/
+│   ├── address_parse/              # ArkTS module source
+│   │   ├── src/main/ets/
+│   │   │   ├── AddressParseTurboModule.ets   # core parser (built-in admin-division data)
+│   │   │   └── AddressParsePackage.ets       # Package registration
+│   │   ├── src/main/cpp/
+│   │   │   └── ReactNativeAddressParsePackage.h/.cpp  # C++ glue layer
+│   │   └── oh-package.json5
+│   └── react_native_address_parse.har  # prebuilt HAR artifact
+└── package.json                    # includes harmony.autolinking config
+```
+
+## Compatibility
+
+| Item | Description |
+|------|-------------|
+| RNOH version | 0.84.x |
+| HarmonyOS / OpenHarmony | API 12+ (modelVersion 26.0.0) |
+| Architecture | Fabric + TurboModule (New Architecture) |
+
+## Usage
+
+The API is identical to the original library:
+
+```tsx
+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: ''
+// }
+```
+
+Optional options:
+
+```tsx
+parseAddress(address, {
+  type: 0,              // 0: normal mode (default), 1: extra gov data mode
+  textFilter: [],       // keywords to filter out
+  nameMaxLength: 0,     // max name length, 0 = unlimited
+  extraGovData: { province: [], city: [], area: [] },  // custom admin divisions
+});
+```
+
+## Integration (host project)
+
+1. After `npm install react-native-address-parse`, add to `harmony/oh-package.json5` and `harmony/entry/oh-package.json5`:
+
+```json5
+"dependencies": {
+  "@rnoh/react-native-address-parse--address_parse": "file:../node_modules/react-native-address-parse/harmony/react_native_address_parse.har",
+}
+```
+
+2. Run `ohpm install` again; autolinking will generate `RNOHPackagesFactory.ets` / `autolinking.cmake` and link the C++ Package (class name `ReactNativeAddressParsePackage`).
+
+3. Rebuild the JS bundle (`npx react-native bundle-harmony`) and the HAP.
+
+## Implementation Notes
+
+- Address parsing and admin-division matching run synchronously on the ArkTS side via the TurboModule `parse` method; built-in data covers 34 provinces (incl. HK/MO/TW) / 392 cities / 3209 districts.
+- **Admin-division data source**: [AreaCity-JsSpider-StatsGov](https://github.com/xiangyuecn/AreaCity-JsSpider-StatsGov) release `2025.251231.260403` (collected 2026-04-03, includes latest changes such as Chongqing Liangjiang New Area). It aggregates [National Place Name Information Base](https://dmfw.mca.gov.cn/) (2025-12-31; the authoritative official source since MCA/MoS stopped publishing division codes in 2026), Tencent Maps divisions v20251119 and AMap divisions. The generated `.ets` data files also carry the source attribution in their headers — do not edit them manually.
+- The C++ glue layer must declare `methodMap_` in the `ArkTSTurboModule` subclass constructor (`ARK_METHOD_METADATA(parse, 5)`); otherwise the TM registers but JS calls fail with "undefined is not a function".
+- Host oh-package dependency keys must carry the HAR module suffix (`--address_parse`).
+- If "Cannot find module" appears after upgrading the HAR, delete `harmony/entry/src/main/ets/RNOHPackagesFactory.ets` and both `oh-package-lock.json5` files, then reinstall.
+
+## License
+
+MIT © zh-address-parse contributors. Adaptation for HarmonyOS/OpenHarmony under the same MIT license.

package/README.OpenHarmony_CN.md

@@ -0,0 +1,97 @@
+# react-native-address-parse HarmonyOS 适配文档
+
+> 基于 [zh-address-parse](https://github.com/zhaocjcc/zh-address-parse) 的鸿蒙适配版。原库为纯 JS 中国地址解析库，本版本将其核心解析算法移植为 ArkTS TurboModule，供 RNOH (React Native OpenHarmony) 项目使用。
+
+## 下载安装
+
+| 资料来源 | 地址 |
+|---------|------|
+| AtomGit | https://atomgit.com/oh-react-native/react-native-address-parse |
+
+```bash
+npm install react-native-address-parse
+```
+
+## 目录结构
+
+```text
+├── 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 完全一致：
+
+```tsx
+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: ''
+// }
+```
+
+可选参数：
+
+```tsx
+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` 添加：
+
+```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](https://github.com/xiangyuecn/AreaCity-JsSpider-StatsGov) `2025.251231.260403` 版（2026-04-03 采集，含重庆两江新区等最新变更）。该数据聚合自 [国家地名信息库](https://dmfw.mca.gov.cn/)（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)](https://opensource.org/licenses/mit-license.php) ，请自由地享受和参与开源。

package/harmony/AppScope/app.json5

@@ -0,0 +1,10 @@
+{
+  "app": {
+    "bundleName": "com.rnoh.addressparse",
+    "vendor": "react-native-address-parse",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "icon": "$media:app_icon",
+    "label": "$string:app_name"
+  }
+}

package/harmony/AppScope/resources/base/element/string.json

@@ -0,0 +1,8 @@
+{
+  "string": [
+    {
+      "name": "app_name",
+      "value": "address_parse"
+    }
+  ]
+}

package/harmony/address_parse/BuildProfile.ets

@@ -0,0 +1,17 @@
+/**
+ * Use these variables when you tailor your ArkTS code. They must be of the const type.
+ */
+export const HAR_VERSION = '1.0.0';
+export const BUILD_MODE_NAME = 'debug';
+export const DEBUG = true;
+export const TARGET_NAME = 'default';
+
+/**
+ * BuildProfile Class is used only for compatibility purposes.
+ */
+export default class BuildProfile { 
+	static readonly HAR_VERSION = HAR_VERSION;
+	static readonly BUILD_MODE_NAME = BUILD_MODE_NAME;
+	static readonly DEBUG = DEBUG;
+	static readonly TARGET_NAME = TARGET_NAME;
+}

package/harmony/address_parse/Index.ets

@@ -0,0 +1,2 @@
+export { AddressParsePackage } from './src/main/ets/AddressParsePackage';
+export { AddressParsePackage as default } from './src/main/ets/AddressParsePackage';

package/harmony/address_parse/build-profile.json5

@@ -0,0 +1,11 @@
+{
+  "apiType": "stageMode",
+  "targets": [
+    {
+      "name": "default"
+    },
+    {
+      "name": "ohosTest"
+    }
+  ]
+}

package/harmony/address_parse/hvigor/hvigor-config.json5

@@ -0,0 +1,8 @@
+{
+  "modelVersion": "26.0.0",
+  "dependencies": {},
+  "execution": {},
+  "logging": {},
+  "debugging": {},
+  "nodeOptions": {}
+}

package/harmony/address_parse/hvigorfile.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2026 react-native-address-parse contributors.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { harTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+  system: harTasks, /* Built-in plugin of Hvigor. It cannot be modified. */
+  plugins: [] /* Custom plugin to extend the functionality of Hvigor. */
+};

package/harmony/address_parse/oh-package.json5

@@ -0,0 +1,22 @@
+{
+  "modelVersion": "26.0.0",
+  "name": "@rnoh/react-native-address-parse",
+  "version": "1.0.0",
+  "description": "HarmonyOS/OpenHarmony adaptation package for react-native-address-parse",
+  "main": "Index.ets",
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@rnoh/react-native-openharmony": "^0.84.3"
+  },
+  "metadata": {
+    "sourceRoots": [
+      "./src/main"
+    ],
+    "debug": true
+  },
+  "compatibleSdkVersionStage": "beta1",
+  "compatibleSdkVersion": 12,
+  "compatibleSdkType": "HarmonyOS",
+  "obfuscated": false
+}

package/harmony/address_parse/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.5)
+set(CMAKE_VERBOSE_MAKEFILE on)
+
+file(GLOB address_parse_SRC CONFIGURE_DEPENDS *.cpp)
+
+add_library(rnoh__react_native_address_parse SHARED ${address_parse_SRC})
+target_include_directories(rnoh__react_native_address_parse PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(rnoh__react_native_address_parse PUBLIC rnoh)

package/harmony/address_parse/src/main/cpp/ReactNativeAddressParsePackage.cpp

@@ -0,0 +1 @@
+#include "ReactNativeAddressParsePackage.h"

package/harmony/address_parse/src/main/cpp/ReactNativeAddressParsePackage.h

@@ -0,0 +1,44 @@
+#pragma once
+
+#include "RNOH/Package.h"
+#include "RNOH/ArkTSTurboModule.h"
+#include "RNOH/TurboModuleFactory.h"
+
+namespace rnoh {
+
+// JS 可见的方法表必须在此声明（等价于 codegen 生成的 spec）：
+// parse(address, type, textFilter, nameMaxLength, extraGovData) 返回 ParseResult。
+class AddressParseArkTSTurboModule : public ArkTSTurboModule {
+ public:
+  AddressParseArkTSTurboModule(
+      const ArkTSTurboModule::Context ctx,
+      const std::string name)
+      : rnoh::ArkTSTurboModule(ctx, name) {
+    methodMap_ = {
+        ARK_METHOD_METADATA(parse, 5),
+    };
+  }
+};
+
+class AddressParseTurboModuleFactoryDelegate : public TurboModuleFactoryDelegate {
+ public:
+  SharedTurboModule createTurboModule(Context ctx, const std::string& name) const override {
+    if (name == "AddressParse") {
+      return std::make_shared<AddressParseArkTSTurboModule>(ctx, name);
+    }
+    return nullptr;
+  }
+};
+
+class ReactNativeAddressParsePackage : public rnoh::Package {
+  using Super = rnoh::Package;
+
+ public:
+  using Super::Super;
+
+  std::unique_ptr<TurboModuleFactoryDelegate> createTurboModuleFactoryDelegate()
+      override {
+    return std::make_unique<AddressParseTurboModuleFactoryDelegate>();
+  }
+};
+} // namespace rnoh

package/harmony/address_parse/src/main/ets/AddressParsePackage.ets

@@ -0,0 +1,10 @@
+import { RNOHPackage, AnyThreadTurboModule, AnyThreadTurboModuleContext } from '@rnoh/react-native-openharmony';
+import { AddressParseTurboModule } from './AddressParseTurboModule';
+
+export class AddressParsePackage extends RNOHPackage {
+  override getAnyThreadTurboModuleFactoryByNameMap(): Map<string, (ctx: AnyThreadTurboModuleContext) => AnyThreadTurboModule | null> {
+    return new Map([
+      [AddressParseTurboModule.NAME, (ctx) => new AddressParseTurboModule(ctx)],
+    ]);
+  }
+}