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

v1.3.1-beta.1

Published

2 days ago

Effortlessly enable edge-to-edge display in React Native

0High
0Medium
0Low

react-native harmony harmonyos

react-native-edge-to-edge

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

项目介绍

react-native-edge-to-edge 帮助 React Native 应用启用 edge-to-edge（沉浸式）显示：应用内容延伸绘制到状态栏与底部导航区域之下，系统栏默认透明。通过 <SystemBars /> 组件统一管理状态栏/导航栏的图标明暗与显隐，支持 style/hidden 属性及命令式栈操作（pushStackEntry / popStackEntry / replaceStackEntry）。

本仓库为鸿蒙（OpenHarmony）适配版本（当前版本 1.3.1-beta.1），包含 JS 层与原生 TurboModule（RNEdgeToEdge）。鸿蒙端通过 Window.setWindowLayoutFullScreen(true) 实现沉浸式布局，通过 setWindowSystemBarProperties / setSpecificSystemBarEnabled 管理系统栏样式与显隐；业务代码仍使用原库名 react-native-edge-to-edge 导入，无需改动现有 import 路径。

集成指南

安装鸿蒙适配包：

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

安装后，业务代码继续使用原库名导入（由 harmony.alias 自动重定向）：

import { SystemBars } from 'react-native-edge-to-edge';

Peer 依赖（与包信息 peerDependencies / engines 一致）：

| 依赖 | 版本要求 | |------|----------| | react-native | >=0.72 | | react | >=18.2.0 | | Node.js | >=18 |

本模块已配置 harmony.autolinking（ETS/C++ 类名 EdgeToEdgePackage，CMake 目标名 edge_to_edge，HAR 包名 @hxa-rn/react-native-edge-to-edge）。工程接入 RNOH Autolink 后通常无需手动注册。

Autolink 未生效时的备选步骤（不是必做）：在 entry/oh-package.json5 引入 HAR，在 C++ 与 ETS 侧注册 EdgeToEdgePackage，并链接 CMake 目标 edge_to_edge。HAR 通过 harmony/edge_to_edge/index.ets 默认导出 EdgeToEdgePackage，使用默认导入，不带 /ts 子路径。

"dependencies": {
  "@hxa-rn/react-native-edge-to-edge": "file:../../node_modules/@hxa-rn/react-native-edge-to-edge/harmony/edge_to_edge.har"
}

C++ 备选（entry/src/main/cpp/PackageProvider.cpp）：

#include "EdgeToEdgePackage.h"

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

ETS 备选（entry/src/main/ets/RNPackagesFactory.ets）：

import EdgeToEdgePackage from '@hxa-rn/react-native-edge-to-edge';

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

CMake 备选：对 oh_modules/@hxa-rn/react-native-edge-to-edge/src/main/cpp 执行 add_subdirectory，并将目标 edge_to_edge 加入 target_link_libraries。然后执行 ohpm install。

插件 HAR 的 requestPermissions 为空，无额外系统权限。

使用说明

基本用法：统一设置系统栏样式

import { SystemBars } from 'react-native-edge-to-edge';

const App = () => (
  <>
    {/* style="auto"：浅色主题显示深色图标，深色主题显示浅色图标 */}
    <SystemBars style="auto" />
    {/* ... */}
  </>
);

分别控制状态栏与导航栏

接续上一节，已从 react-native-edge-to-edge 导入 SystemBars。

import { SystemBars } from 'react-native-edge-to-edge';

<SystemBars
  style={{ statusBar: 'light', navigationBar: 'dark' }}
  hidden={{ statusBar: false, navigationBar: true }}
/>

命令式栈操作

多个 <SystemBars /> 实例或命令式调用会通过栈合并配置，后挂载、层级更深的实例优先：

import { SystemBars } from 'react-native-edge-to-edge';

// 压栈
const entry = SystemBars.pushStackEntry({ style: 'light', hidden: { statusBar: true } });

// 出栈
SystemBars.popStackEntry(entry);

// 替换栈顶
const newEntry = SystemBars.replaceStackEntry(entry, { style: 'dark' });

pushStackEntry / replaceStackEntry 同步返回栈条目；popStackEntry 无返回值。三者均在下一帧通过原生 TurboModule 应用配置。JS 层本身不抛业务错误；原生窗口调用失败时仅写 hilog，不回传到 JS。

接口文档

类型

| 类型 | 说明 | |------|------| | SystemBarStyle | 'auto' \| 'light' \| 'dark'（已从入口导出） | | SystemBarsProps | { style?: SystemBarStyle \| { statusBar?: SystemBarStyle; navigationBar?: SystemBarStyle }; hidden?: boolean \| { statusBar?: boolean; navigationBar?: boolean } }（已导出） | | SystemBarsEntry | 栈条目，含 statusBarStyle、statusBarHidden、navigationBarStyle、navigationBarHidden（已导出） |

style / hidden 可为单值或分栏对象；入口未单独导出内部别名。

`<SystemBars />` 组件

| 属性 | 类型 | 说明 | |------|------|------| | style | SystemBarStyle \| { statusBar?, navigationBar? } | 系统栏图标明暗样式；'auto' 随系统颜色方案解析为 light 或 dark | | hidden | boolean \| { statusBar?, navigationBar? } | 隐藏/显示状态栏或底部导航区域 |

组件不渲染任何 UI（返回 null），挂载/卸载/属性变化时自动更新原生系统栏。
多实例通过栈式机制合并，卸载后回退到上一实例配置。

静态方法

| 方法 | 签名 | 返回值 | 说明 | |------|------|--------|------| | SystemBars.pushStackEntry | (props: SystemBarsProps) => SystemBarsEntry | SystemBarsEntry | 命令式压栈，返回 entry 供出栈使用 | | SystemBars.popStackEntry | (entry: SystemBarsEntry) => void | 无 | 出栈并更新原生系统栏 | | SystemBars.replaceStackEntry | (entry: SystemBarsEntry, props: SystemBarsProps) => SystemBarsEntry | SystemBarsEntry | 替换栈顶配置 |

内部 TurboModule（`RNEdgeToEdge`，不对外导出）

由 <SystemBars /> 和 Spec 模块自动调用，业务层无需直接使用：

| 方法 | 说明 | |------|------| | onColorSchemeChange() | 系统颜色方案变化时重新应用 edge-to-edge 沉浸式布局 | | setSystemBarsConfig(config) | 应用系统栏配置（statusBarStyle / statusBarHidden / navigationBarStyle / navigationBarHidden） |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18（运行 Example 建议 >= 20，见 example/package.json） | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 21+（example/harmony 的 compatibleSdkVersion 为 6.0.1(21)） |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-is-edge-to-edge.git
cd react-native-is-edge-to-edge
git checkout br_rnoh0.72

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

4. 安装鸿蒙依赖

cd harmony
ohpm install

5. 用 DevEco Studio 打开鸿蒙工程

打开 DevEco Studio
选择 example/harmony 目录
首次构建请在 File → Project Structure → Signing Configs 勾选 Automatically generate signature，Apply 后 Sync
等待 Sync 完成

6. 编译并运行 HAP

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

注意：Example 已预置 Autolinking Package 注册、Metro alias 与 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

约束与限制

| 项目 | 说明 | | --- | --- | | React Native / RNOH | 对等依赖 react-native >= 0.72。Example 使用 [email protected] 与 @react-native-oh/[email protected]（TurboModule 新架构） | | HarmonyOS SDK | example/harmony 的 compatibleSdkVersion 为 6.0.1(21) | | Node.js | 根目录 engines.node 为 >=18；运行 Example 建议 >=20 | | 权限 | 库 HAR requestPermissions 为空；使用主窗口能力（getLastWindow / setWindowLayoutFullScreen / setWindowSystemBarProperties / setSpecificSystemBarEnabled），无额外系统权限 | | 架构 | 仅支持 TurboModule 新架构，不支持旧架构 Interop Layer | | 导航栏图标明暗 | style.navigationBar 在部分 HarmonyOS 设备上可能无可见变化（SDK 标注 isNavigationBarLightIcon 各设备不支持）；状态栏 style 与显隐仍可用 | | 场景限制 | 自由窗口、分屏、悬浮窗下 setWindowLayoutFullScreen / setSpecificSystemBarEnabled 可能不生效；以全屏/最大化主窗口为准 | | Expo | 上游 Android Expo config plugin 在鸿蒙端不适用；沉浸式布局由 TurboModule 在运行时应用 |

开源license

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

问题反馈渠道

GitCode 仓库：https://gitcode.com/hxa-rn/react-native-is-edge-to-edge
Issue 反馈：https://gitcode.com/hxa-rn/react-native-is-edge-to-edge/issues