@bingtang-rn/react-native-inappbrowser-nitro for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-inappbrowser-nitro

使用

import {
  open,
  openAuth,
  close,
  closeAuth,
  isAvailable,
  useInAppBrowser,
} from 'react-native-inappbrowser-nitro'

// Open an in-app browser
const result = await open('https://github.com', {
  preferredBarTintColor: { base: '#2563EB' },
  preferredControlTintColor: { base: '#FFFFFF' },
  showTitle: true,
  dismissButtonStyle: 'close',
})

// Open an auth session
const authResult = await openAuth(
  'https://example.com/oauth',
  'myapp://callback',
  { toolbarColor: { base: '#2563EB' } }
)

// Use the hook
const { open, isLoading, error } = useInAppBrowser()

import 时使用原库名 'react-native-inappbrowser-nitro'，而非鸿蒙包名。

平台差异：

• HarmonyOS 使用独立 UIAbility + Web 组件实现，浏览器以全屏 Ability 形式展示
• isAvailable() 在 HarmonyOS 上始终返回 true
• 部分平台专属选项在 HarmonyOS 上被忽略（详见下方 API_NOTES）

权限要求：

• 需在 module.json5 声明 ohos.permission.INTERNET
• 需在 example 的 module.json5 注册 BrowserManagerAbility
• 需在 EntryAbility.onCreate 调用 webview.WebviewController.initializeWebEngine() 初始化 Web 引擎

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-inappbrowser-nitro": "file:../../node_modules/@bingtang-rn/react-native-inappbrowser-nitro/harmony/inappbrowser_nitro.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-inappbrowser-nitro/src/main/cpp" ./inappbrowser_nitro)

target_link_libraries(rnoh_app PUBLIC inappbrowser_nitro)

4. 注册 Package（C++ 侧）

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

#include "InappbrowserNitroPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { InappbrowserNitroPackage } from '@bingtang-rn/react-native-inappbrowser-nitro/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | isAvailable | 检测设备是否支持应用内浏览器 | 无 | Promise<boolean> | ✅ 完全支持（始终返回 true） | | open | 打开应用内浏览器 | url: string, options?: InAppBrowserOptions | Promise<InAppBrowserResult> | ⚠️ 部分支持（核心功能完整，部分选项被忽略） | | openAuth | 打开认证会话 | url: string, redirectUrl: string, options?: InAppBrowserOptions | Promise<InAppBrowserAuthResult> | ⚠️ 部分支持（核心功能完整，部分选项被忽略） | | close | 关闭浏览器 | 无 | Promise<void> | ✅ 完全支持 | | closeAuth | 关闭认证会话 | 无 | Promise<void> | ✅ 完全支持 | | useInAppBrowser | React Hook 封装 | 无 | UseInAppBrowserReturn | ✅ 完全支持（JS 层实现） |

平台差异

• open/openAuth：HarmonyOS 使用独立 UIAbility + Web 组件，浏览器以全屏窗口展示（等同于 fullScreen 模态样式）
• isAvailable：HarmonyOS 始终返回 true（内置 Web 引擎）
• close/closeAuth：通过 terminateSelf() 终止浏览器 Ability 实现
• 认证流程：通过 onPageEnd 拦截匹配 redirectUrl 前缀的导航实现

已支持的浏览器选项

| 选项 | 说明 | |------|------| | preferredBarTintColor | 工具栏背景色（支持 DynamicColor 的 base 字段） | | preferredControlTintColor | 工具栏文字/图标色（支持 DynamicColor 的 base 字段） | | toolbarColor | 工具栏背景色（与 preferredBarTintColor 合并） | | showTitle | 是否显示页面标题 | | dismissButtonStyle | 关闭按钮文字（done/close/cancel） | | colorScheme | 深色/浅色模式（dark/light/system） |

未实现功能

| 选项 | 原因 | |------|------| | readerMode | HarmonyOS Web 组件无 Reader Mode API | | modalPresentationStyle / modalTransitionStyle | 无 UIKit 模态概念 | | enableBarCollapsing | Web 组件无自动折叠工具栏能力 | | ephemeralWebSession | 需额外 WebCookie 管理开发 | | enableEdgeDismiss | 系统级返回手势由系统控制 | | enableUrlBarHiding | Web 组件无自动隐藏 URL 栏能力 | | enableDefaultShare / shareState | 无系统分享集成 | | animations | ArkUI 使用属性动画，不支持 XML 动画 | | browserPackage | HarmonyOS 无多浏览器选择概念 | | headers | 需通过 onInterceptRequest 实现，复杂度高 | | forceCloseOnRedirection | 无对应能力 | | enablePullToRefresh | Web 组件下拉刷新行为不同 | | enablePartialCustomTab | 无对应概念 |

使用限制

• 需声明 ohos.permission.INTERNET
• 需在应用中注册 BrowserManagerAbility（见 Example 的 module.json5）
• 需在 EntryAbility 中初始化 ArkWeb 引擎

快速验证（运行 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+

遗留问题

无（或列出已知问题）

开源协议

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