react-native-system-navigation-bar

本项目基于 react-native-system-navigation-bar开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-system-navigation-bar 是 react-native-system-navigation-bar 的鸿蒙适配包（版本 2.8.5），提供与上游一致的 JS API，用于控制系统导航栏 / 状态栏的显示、颜色与沉浸行为。

集成指南

npm install @hxa-rn/react-native-system-navigation-bar

import 时使用原库名 'react-native-system-navigation-bar'（harmony.alias），而非鸿蒙包名 '@hxa-rn/react-native-system-navigation-bar'。

peerDependencies：react、react-native（>=0.72）。

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

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

"dependencies": {
  "@hxa-rn/react-native-system-navigation-bar": "file:../../node_modules/@hxa-rn/react-native-system-navigation-bar/harmony/system_navigation_bar.har"
}

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

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-system-navigation-bar/src/main/cpp" ./system_navigation_bar)

target_link_libraries(rnoh_app PUBLIC system_navigation_bar)

#include "SystemNavigationBarPackage.h"

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

import { SystemNavigationBarPackage } from '@hxa-rn/react-native-system-navigation-bar/ts';

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

使用说明

import SystemNavigationBar, { GetBarColorType } from 'react-native-system-navigation-bar';

export async function navigationDemo() {
  await SystemNavigationBar.navigationHide();
  await SystemNavigationBar.navigationShow();
  await SystemNavigationBar.leanBack();
  await SystemNavigationBar.setNavigationColor('#80b3ff', 'dark', 'both');
  const barColors: GetBarColorType = await SystemNavigationBar.getBarColor('both');
  console.log(barColors);
}

平台差异摘要：

• 沉浸模式三态在鸿蒙行为一致：隐藏系统栏并进入全屏布局；触摸/边缘唤回需宿主自行模拟。
• 导航栏图标明暗不生效，仅状态栏（bar='status'/'both'）生效。
• 导航栏颜色通过窗口背景色近似呈现；setNavigationColor 的 bar 作用范围严格生效（'transparent' / 'translucent' 除外）。
• lowProfile 降级为隐藏系统栏（不进入全屏布局）；setNavigationBarDividerColor / setNavigationBarContrastEnforced 为 no-op。
• 内容延伸需宿主配合 SafeAreaView 放弃对应方向避让；setFitsSystemWindows(true) 的避让同样由 SafeAreaView 的 inset 提供。

宿主接入：让内容延伸到系统栏区域

隐藏系统栏后，需让 SafeAreaView 显式传入 paddingTop / paddingBottom 以跳过对应 inset（传单个 style 对象，勿传数组）：

import React from 'react';
import { SafeAreaView, View, Text } from 'react-native';

export function Screen({ navigationHidden }: { navigationHidden: boolean }) {
  return (
    <SafeAreaView style={navigationHidden ? { flex: 1, paddingBottom: 0 } : { flex: 1 }}>
      <View style={{ flex: 1 }}>
        <Text>内容区</Text>
      </View>
    </SafeAreaView>
  );
}

宿主接入：模拟 Lean Back / Immersive 唤回系统栏

鸿蒙隐藏系统栏后不会因触摸或边缘滑动自动恢复，需宿主在 RN 侧用 onTouchStart / onTouchMove 自行模拟唤回（例如触摸任意处调用 navigationShow()，或边缘滑动后退出沉浸模式）。

宿主接入：自绘导航栏分隔线

鸿蒙无导航栏分隔线能力，接口为 no-op；宿主可在内容区最下缘自绘同色细线。

接口文档

平台差异

• 沉浸模式三态统一映射为隐藏系统栏 + 全屏布局；无 Android 触摸/边缘自动唤回语义。
• lowProfile 降级为隐藏状态栏与底部导航指示条，且不调用 setWindowLayoutFullScreen。
• 导航栏图标明暗不支持；状态栏需同时写 isStatusBarLightIcon 与 statusBarContentColor。
• 导航栏颜色无直接 API，通过窗口背景色近似；bar='navigation' 时会先钉住状态栏不透明色。
• getBarColor 的导航栏色由模块内部跟踪，未设置时回退窗口默认背景色。 transparent / translucent 之后查询导航栏为 #000000（对齐 Android 丢掉 alpha 后的 Color.TRANSPARENT）， 不表示半透明蒙版色值，也不能单独证明内容已延伸进导航区。
• setFitsSystemWindows 只有 enabled=false（内容延伸）写窗口布局 setWindowLayoutFullScreen(true)； enabled=true 的避让由宿主 SafeAreaView 的 inset 提供，原生不会写 setWindowLayoutFullScreen(false) ——RNOH 的 SafeAreaInsetsProvider 只按 getWindowAvoidArea 算 padding、不看布局标记，窗口避让会与 SafeAreaView 的 inset 叠加，状态栏下方出现空白带（navigationShow / 退出沉浸同理）。

未实现 / no-op

快速验证（运行 Example）

前置条件

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-system-navigation-bar.git
cd react-native-system-navigation-bar
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-system-navigation-bar@2.8.5，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

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

cd example          # 或 example_auto
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（或 example_auto/harmony）目录
• 等待 Sync 完成

6. 编译并运行 HAP

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

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

约束与限制

兼容性

• 鸿蒙 SDK：API 12+
• 上游 RN 库：react-native-system-navigation-bar 2.8.0
• React Native / RNOH：0.72+
• DevEco Studio：5.0+

权限

• 无额外系统权限。

其他限制

• 系统栏控制依赖全屏/最大化模式；非全屏/最大化下配置可能不生效。
• 挖孔屏由系统自动处理。
• 导航栏颜色为近似实现，与 Android 精确色存在色差。

开源license

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

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-system-navigation-bar

https://gitcode.com/hxa-rn/react-native-system-navigation-bar/issues