@bingtang-rn/react-native-exceptions-manager for HarmonyOS

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

版本对应关系

安装

npm install @bingtang-rn/react-native-exceptions-manager

使用

import RKExceptionsManager from 'react-native-exceptions-manager';

// 报告致命异常（JS 层捕获后发送到宿主应用）
RKExceptionsManager.reportFatalException(
  'Unhandled JS Error',
  [
    { methodName: 'render', file: 'index.bundle', lineNumber: 42, column: 15 },
    { methodName: 'processChild', file: '123.js', lineNumber: 100 },
  ],
  1,
);

// 报告非致命异常（仅记录日志）
RKExceptionsManager.reportSoftException(
  'Soft Error',
  [{ methodName: 'onPress', file: 'App.js', lineNumber: 30 }],
  2,
);

import 时使用原库名 'react-native-exceptions-manager'，而非鸿蒙包名（RNOH alias 自动映射）。

平台差异：

• HarmonyOS 上 reportFatalException 通过 commonEventManager.publish 发布自定义公共事件（对应 Android 的 sendBroadcast），宿主应用需通过 commonEventManager.subscribe 订阅 action 为 com.richardcao.android.REACT_NATIVE_CRASH_REPORT_ACTION 的事件来接收异常信息。
• reportSoftException 在 HarmonyOS 上通过 hilog.error 输出日志（对应 Android 的 FLog.e）。

权限要求：

• 发布自定义公共事件无需额外权限声明。

Link

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

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

"dependencies": {
  "@bingtang-rn/react-native-exceptions-manager": "file:../../node_modules/@bingtang-rn/react-native-exceptions-manager/harmony/exceptions_manager.har"
}

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

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-exceptions-manager/src/main/cpp" ./exceptions_manager)

target_link_libraries(rnoh_app PUBLIC exceptions_manager)

#include "ExceptionsManagerPackage.h"

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

import { ExceptionsManagerPackage } from '@bingtang-rn/react-native-exceptions-manager/ts';

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

属性 / API

平台差异

• reportFatalException：Android 使用 BroadcastReceiver + Intent 发送异常广播；HarmonyOS 使用 commonEventManager.publish 发布自定义公共事件，宿主需订阅相同 action 接收。异常信息以 parameters['JavascriptException'] 字符串传递（Android 为 RuntimeException 对象 extra）。
• reportSoftException：Android 使用 FLog.e 输出；HarmonyOS 使用 hilog.error 输出。

未实现功能

使用限制

• 模块名 RKExceptionsManager 与 RN 内置 ExceptionsManager 同名，原 Android 端通过 canOverrideExistingModule=true 覆盖系统模块。HarmonyOS 上是否能覆盖系统模块取决于 RNOH 版本和运行时行为。

快速验证（运行 Example）

前置条件

运行步骤

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+

遗留问题

• NativeModuleCallExceptionHandler 功能未实现：RNOH 框架无等效机制，宿主应用需自行使用 errorManager.on('error') 捕获全局异常。

开源协议

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