@hxa-rn/react-native-edge-to-edge

本项目基于 react-native-edge-to-edge 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

本库用于在 React Native 应用中便捷地启用 edge-to-edge 显示，并统一管理状态栏与导航栏。

• 通过 SystemBars 组件配置状态栏和导航栏样式及显隐状态。
• 提供配置栈管理，可在多个 SystemBars 实例之间按层级合并配置。
• 提供 pushStackEntry、popStackEntry、replaceStackEntry、setStyle 和 setHidden 命令式 API。
• 在 HarmonyOS 端通过 TurboModule 调用窗口系统栏能力并启用沉浸式布局。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-edge-to-edge

库要求宿主工程提供 react-native >=0.72 和 react，Node.js 要求为 >=18。

Autolinking

安装依赖后由宿主工程自动接入，无需手动注册。

导入

import { SystemBars } from "@hxa-rn/react-native-edge-to-edge";
import type {
  SystemBarStyle,
  SystemBarsEntry,
  SystemBarsProps,
} from "@hxa-rn/react-native-edge-to-edge";

使用说明

基础用法

import { SystemBars } from "@hxa-rn/react-native-edge-to-edge";

export default function App() {
  return <SystemBars style="auto" hidden={false} />;
}

style 和 hidden 支持统一设置，也支持分别设置状态栏与导航栏。SystemBars 挂载时将配置压入配置栈，卸载时移除自身配置并恢复栈中的下一层配置。

分别配置系统栏

import { SystemBars } from "@hxa-rn/react-native-edge-to-edge";

export function Screen() {
  return (
    <SystemBars
      style={{ statusBar: "light", navigationBar: "dark" }}
      hidden={{ statusBar: false, navigationBar: true }}
    />
  );
}

样式取值为 auto、inverted、light 和 dark。其中 auto 根据当前颜色方案选择内容样式，inverted 选择相反样式；light 和 dark 分别指定浅色或深色系统栏内容。

接口文档

以下 API 依据 src/index.ts、src/SystemBars.ts、src/types.ts 和 src/specs/v1/NativeEdgeToEdgeModule.ts 整理。

SystemBars

管理系统栏样式和显隐状态的组件，同时提供命令式静态方法。

属性	类型	默认值	说明
style	SystemBarStyle | { statusBar?: SystemBarStyle; navigationBar?: SystemBarStyle }	未声明	设置统一的系统栏样式，或分别设置状态栏和导航栏样式。
hidden	boolean | { statusBar?: boolean; navigationBar?: boolean }	未声明	设置统一的系统栏显隐状态，或分别设置状态栏和导航栏显隐状态。

SystemBars.pushStackEntry(props)

将配置压入系统栏配置栈，并返回对应的 SystemBarsEntry。

const entry = SystemBars.pushStackEntry({ style: "dark" });

SystemBars.popStackEntry(entry)

从配置栈中移除由 pushStackEntry 返回的条目，并应用移除后的配置。

SystemBars.popStackEntry(entry);

SystemBars.replaceStackEntry(entry, props)

用新属性替换配置栈中的条目，并返回新的 SystemBarsEntry 引用。

const nextEntry = SystemBars.replaceStackEntry(entry, { style: "light" });

SystemBars.setStyle(style)

直接设置当前系统栏样式，不修改配置栈。参数类型为 SystemBarsProps["style"]。

SystemBars.setStyle("dark");
SystemBars.setStyle({ statusBar: "light", navigationBar: "dark" });

SystemBars.setHidden(hidden)

直接设置当前系统栏显隐状态，不修改配置栈。参数类型为 SystemBarsProps["hidden"]。

SystemBars.setHidden(true);
SystemBars.setHidden({ statusBar: false, navigationBar: true });

TurboModule 接口

JS Spec 中的 TurboModule 注册名为 RNEdgeToEdge，包含以下方法：

方法	参数	返回值	说明
setStatusBarStyle	style: string	void	设置状态栏样式。
setNavigationBarStyle	style: string	void	设置导航栏样式。
setStatusBarHidden	hidden: boolean	void	设置状态栏显隐状态。
setNavigationBarHidden	hidden: boolean	void	设置导航栏显隐状态。
onColorSchemeChange	无	void	响应颜色方案变化。

runErrorHandlingDiagnostic(): Promise<string> 仅存在于当前 Spec 和 Example 的异常处理诊断路径中，不属于模块根入口导出的普通业务 API。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>=20
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+

运行步骤

1. 获取开发分支源码：

   git clone -b react-native-edge-to-edge_dev https://gitcode.com/hxa-rn/react-native-edge-to-edge.git
   

2. 进入仓库根目录：

   cd react-native-edge-to-edge
   

3. 安装根目录依赖：

   npm i
   

4. 生成供示例工程安装的本地安装包：

   npm pack
   

5. 进入 example 目录：

   cd example
   

6. 安装示例工程依赖：

   npm i
   

7. 生成 React Native JavaScript Bundle：

   npm run dev
   

8. 使用 DevEco Studio 打开 example/harmony，同步依赖，完成签名配置后构建并运行。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	>=18

使用限制

• HarmonyOS 端在 TurboModule 初始化时尝试启用沉浸式布局；沉浸式布局不能据此推断状态栏一定会被隐藏。
• 自由窗口、悬浮窗、分屏等非全屏或非最大化模式下，窗口系统栏配置可能不生效；切换到全屏或最大化模式后才可能生效。
• HarmonyOS 端导航栏内容颜色受系统能力限制，setNavigationBarStyle 调用可以执行，但可能不会产生预期的颜色变化。
• 状态栏和导航指示器的显隐受 HarmonyOS 系统栏联动规则影响。

系统权限

本库不依赖额外的 HarmonyOS 系统权限。

开源 License

本项目采用 MIT，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。