检测是否安装/启用 edge-to-edge（全面屏边到边）相关能力

@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 在运行时应用