@bingtang-rn/react-native-ultimate-config for HarmonyOS

本项目基于 react-native-ultimate-config 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 6.0.1 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-ultimate-config

使用

import Config from 'react-native-ultimate-config';

// 读取构建期注入的配置值（string / number / boolean，类型由 env 文件决定）
const appName: string = Config.APP_NAME;
const timeout: number = Config.API_TIMEOUT;
const enableFeature: boolean = Config.ENABLE_FEATURE;

// per-platform 值：YAML 中按 ios/android/web/harmony 声明，Platform.select 自动选分支
const greeting: string = Config.PLATFORM_GREETING;

import 时使用原库名 'react-native-ultimate-config'，鸿蒙包由 RNOH alias 自动映射到 @bingtang-rn/react-native-ultimate-config。

平台差异：

• HarmonyOS 通过 TurboModule UltimateConfig.getConstants() 在运行时返回构建期生成的 ConfigValues.ets 中嵌入的常量字典，替代 Android BuildConfig 反射与 iOS #define 宏注入。
• 构建期注入机制：hvigor 无 Gradle 插件 / xcconfig 等价物，配置值改为 CLI 直接生成 ArkTS 源码（ConfigValues.ets），TurboModule 导入并返回，行为与 iOS/Android 对等。

权限要求：

• 无。本库与 Example 全程不涉及任何 HarmonyOS 运行时权限（不读文件、不联网、不访问硬件）。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-ultimate-config": "file:../../node_modules/@bingtang-rn/react-native-ultimate-config/harmony/ultimate_config.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-ultimate-config/src/main/cpp" ./ultimate_config)

target_link_libraries(rnoh_app PUBLIC ultimate_config)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "UltimateConfigPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<UltimateConfigPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { UltimateConfigPackage } from '@bingtang-rn/react-native-ultimate-config/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new UltimateConfigPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | Config（default export） | 读取构建期注入的全部配置值 | 无 | object（键值由 env 文件决定） | ✅ 完全支持 | | Config.KEY | 读取单个配置值 | 无 | string | number | boolean | ✅ 完全支持 | | per-platform 值 | YAML 中按平台声明 {key: {ios, android, web, harmony}} | 无 | 当前平台分支值 | ✅ 完全支持 | | rnuc CLI | 读取 dotenv/YAML，渲染各平台配置源码 | <env file> | 生成的源码文件 | ✅ 完全支持 | | UltimateConfig.getConstants() | TurboModule 返回配置字典 | 无 | Object（实际 Record<string, string\|number\|boolean>） | ✅ 完全支持 | | override.js（Platform.select） | JS 层 per-platform getter | 无 | 当前平台值 | ✅ 完全支持 |

平台差异

• HarmonyOS 用 TurboModule getConstants() 替代旧架构 NativeModules：JS 入口 index.js 在 Platform.OS === 'harmony' 分支调用 TurboModuleRegistry.get('UltimateConfig').getConstants() 取常量字典。
• 构建期注入：Android 走 Gradle rnuc.gradle 注入 BuildConfig/resValue/manifest placeholder；iOS 走 xcconfig + ConfigValues.h #define 宏；HarmonyOS 无等价机制，改为 CLI 直接生成 ConfigValues.ets ArkTS 源码（TurboModule 导入并返回），行为对等。

未实现功能

无。所有公开能力（JS 常量访问、per-platform 值、CLI 配置注入、override 机制、RC 钩子）均已完整实现。

使用限制

• TurboModule Spec 返回类型为 Object（codegen-harmony 拒绝 Record<K,V>），JS 侧 spread 后按属性访问，运行时行为正确，仅 IDE 静态类型提示略宽。
• ConfigValues.ets 由 CLI 生成，修改 env 文件后需重跑 rnuc 重新生成后再构建 HAR/HAP。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无。所有公开能力（JS 常量访问、per-platform 值、CLI 配置注入、override 机制、RC 钩子）均已完整实现，HAR/HAP 构建通过。

开源协议

本项目基于 MIT 协议，详见 LICENSE 文件。