@hxa-rn/react-native-is-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.3），以 @hxa-rn/react-native-is-edge-to-edge 独立发布，包含 JS 层与原生 TurboModule（RNEdgeToEdge）。鸿蒙端通过 Window.setWindowLayoutFullScreen(true) 实现沉浸式布局，通过 setWindowSystemBarProperties / setSpecificSystemBarEnabled 管理系统栏样式与显隐；业务代码直接从 @hxa-rn/react-native-is-edge-to-edge 导入。

集成指南

安装鸿蒙适配包：

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

安装后，业务代码直接使用本包名称导入，不配置上游包名别名：

import { SystemBars } from '@hxa-rn/react-native-is-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-is-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-is-edge-to-edge": "file:../../node_modules/@hxa-rn/react-native-is-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-is-edge-to-edge';

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

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

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

使用说明

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

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

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

分别控制状态栏与导航栏

接续上一节，已从 @hxa-rn/react-native-is-edge-to-edge 导入 SystemBars。

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

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

命令式栈操作

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

import { SystemBars } from '@hxa-rn/react-native-is-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 main

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

cd example
npm install --legacy-peer-deps

example 和 example_auto 均声明 npm 公仓依赖 @hxa-rn/react-native-is-edge-to-edge@^1.3.2，该版本范围包含已发布的 1.3.3。可直接按上述步骤安装。

发布前的本地产物验证：若公仓尚无该版本，在仓库根目录执行以下命令。安装本次待发布的 tgz，不修改 Demo 的依赖声明；后续仍按第 3～6 步生成 Bundle、安装鸿蒙依赖并编译运行。

# 在仓库根目录生成待发布产物
npm install --legacy-peer-deps
npm pack
# 可替换为 cd example_auto 验证另一个 Demo
cd example
npm install ../hxa-rn-react-native-is-edge-to-edge-1.3.3.tgz --no-save --package-lock=false --legacy-peer-deps

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、Metro 与新包名对应的 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

约束与限制

项目	说明
React Native / RNOH	对等依赖 react-native >= 0.72。Example 使用 react-native@0.77.1 与 @react-native-oh/react-native-harmony@0.77.71（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