@bingtang-rn/react-native-navbar for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-navbar

使用

import NavigationBar from 'react-native-navbar';

// 1. 配置对象用法（标题 + 左右按钮 + handler 回调）
const title = { title: '首页', tintColor: '#FFFFFF' };
const leftButton = {
  title: '返回',
  tintColor: '#80D8FF',
  handler: () => console.log('back'),
};
const rightButton = {
  title: '下一步',
  tintColor: '#B9F6CA',
  handler: () => console.log('next'),
};

<NavigationBar
  tintColor="#37474F"
  title={title}
  leftButton={leftButton}
  rightButton={rightButton}
/>

// 2. 自定义元素插槽（title/leftButton/rightButton 传 React 元素）
const whiteText = { color: '#fff' };

<NavigationBar
  tintColor="#4A148C"
  title={<Text style={whiteText}>自定义标题</Text>}
  leftButton={<TouchableOpacity onPress={() => {}}><Text>◀ 返回</Text></TouchableOpacity>}
/>

// 3. 长标题截断 + 样式定制
const longTitle = {
  title: '很长的标题文本会被尾部截断',
  tintColor: '#FFFFFF',
  ellipsizeMode: 'tail',
  numberOfLines: 1,
};
const barStyle = { borderBottomWidth: 1, borderBottomColor: '#ccc' };

<NavigationBar
  tintColor="#006064"
  style={barStyle}
  title={longTitle}
/>

import 时使用原库名 'react-native-navbar'（由 harmony.alias 自动重定向到鸿蒙包），无需使用鸿蒙包名。

平台差异：

• statusBar prop 的状态栏定制逻辑（setBarStyle/showHideTransition/hidden）与顶部状态栏占位 View 在源码中被 Platform.OS === 'ios' 包裹，HarmonyOS 端不进入该分支，属优雅降级——导航栏本体（标题 + 左右按钮）完整渲染，仅不修改系统状态栏外观。如需鸿蒙端状态栏定制，可在应用层调用 @ohos.window 的 setWindowSystemBarProperties。

权限要求：

• 无。本库为纯 UI 组件库，不涉及任何 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-navbar": "file:../../node_modules/@bingtang-rn/react-native-navbar/harmony/navbar.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-navbar/src/main/cpp" ./navbar)

target_link_libraries(rnoh_app PUBLIC navbar)

4. 注册 Package（C++ 侧）

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

#include "NavbarPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { NavbarPackage } from '@bingtang-rn/react-native-navbar/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | title | 标题（配置对象 { title, tintColor, ellipsizeMode, numberOfLines, style } 或 React 元素） | object | element | null | — | ✅ 完全支持 | | leftButton | 左侧按钮（配置对象 { title, tintColor, style, handler, disabled, accessible, accessibilityLabel } 或 React 元素） | object | element | null | — | ✅ 完全支持 | | rightButton | 右侧按钮（同 leftButton） | object | element | null | — | ✅ 完全支持 | | tintColor | 导航栏背景色 | string | — | ✅ 完全支持 | | style | 应用于导航栏本体的样式 | object | array | — | ✅ 完全支持 | | containerStyle | 应用于最外层容器的样式 | object | array | — | ✅ 完全支持 | | statusBar | 状态栏定制 + 顶部占位 | { style, hidden, tintColor, hideAnimation, showAnimation } | — | ⚠️ 部分支持（仅 iOS 生效，鸿蒙端优雅降级） | | 按钮 handler | 按钮点击回调 | function | void | ✅ 完全支持 | | 按钮 disabled | 禁用按钮（不触发 handler） | boolean | — | ✅ 完全支持 | | title.ellipsizeMode / numberOfLines | 标题文本截断 | string / number | — | ✅ 完全支持 |

平台差异

• statusBar prop：源码用 Platform.OS === 'ios' 包裹全部状态栏逻辑（StatusBar.setBarStyle/showHideTransition/hidden）及顶部高 20 的状态栏占位 View。HarmonyOS 端 Platform.OS === 'harmony' 不进入该分支，导航栏本体（标题 + 左右按钮）完整渲染。如需鸿蒙端状态栏定制，可在应用层调用 @ohos.window 的 setWindowSystemBarProperties / setWindowSystemBarEnable（系统级窗口能力）。

使用限制

• 无运行时权限要求。
• 导航栏基于 RN 核心组件（View/Text/TouchableOpacity）由 RNOH 框架映射到 ArkUI，无需原生 Package 注册。

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

遗留问题

• statusBar prop 的状态栏定制（setBarStyle/hidden/动画）与顶部占位 View 仅 iOS 生效，HarmonyOS 端优雅降级（导航栏本体完整渲染）。

开源协议

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