hxa-rn/react-native-modal-translucent

移除Modal上的状态栏背景，支持内容配置、交互控制和样式调整，满足提示、确认及信息展示等场景需求。

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

项目介绍

react-native-modal-translucent 是一个用于控制 React Native Modal 显示期间状态栏效果的 HarmonyOS 适配库。它通过 RNOH TurboModule 控制窗口全屏布局和状态栏背景，使 Modal 内容可以延伸至状态栏区域。

主要能力包括：

setTranslucentStatusBar：启用或取消窗口全屏布局，并设置状态栏透明或默认黑色背景。
restoreStatusBar：恢复首次设置时保存的窗口全屏布局状态，并清除已保存配置。
TranslucentModal：封装 React Native Modal，在 onShow 和 onDismiss 时自动管理状态栏。
提供 NativeModalTranslucent TurboModule，并支持通过 RNOH Autolinking 接入 HarmonyOS HAR 模块。

集成指南

安装

在 React Native 工程根目录执行：

npm install @hxa-rn/react-native-modal-translucent

本库要求宿主工程提供以下 peer dependency：

react-native >=0.72
react >=16.0.0

Autolinking

本库支持 RNOH Autolinking。安装依赖后由宿主工程自动接入，无需手动注册 Package。

导入

import ModalTranslucent, {
  restoreStatusBar,
  setTranslucentStatusBar,
  TranslucentModal,
} from '@hxa-rn/react-native-modal-translucent';

入口实际导出 setTranslucentStatusBar、restoreStatusBar 和 TranslucentModal，默认导出对象包含这三个成员。

使用说明

基础用法

import React, {useState} from 'react';
import {Text, TouchableOpacity, View} from 'react-native';
import {TranslucentModal} from '@hxa-rn/react-native-modal-translucent';

export default function App() {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <Text>打开 Modal</Text>
      </TouchableOpacity>

      <TranslucentModal
        visible={visible}
        transparent={true}
        animationType="slide"
        onRequestClose={() => setVisible(false)}>
        <View>
          <Text>Modal 内容</Text>
          <TouchableOpacity onPress={() => setVisible(false)}>
            <Text>关闭</Text>
          </TouchableOpacity>
        </View>
      </TranslucentModal>
    </View>
  );
}

TranslucentModal 会在传入的 onShow 回调之前调用 setTranslucentStatusBar(true)，并在传入的 onDismiss 回调之前调用 restoreStatusBar()。除这两个回调外，其他属性会通过 ...props 原样传递给 React Native Modal，不会创建额外的原生 UI 组件。

HarmonyOS 版本不会自动覆盖 React Native 内置 Modal；如果不使用该封装组件，需要在原生 Modal 的回调中手动控制状态栏。

import React, {useState} from 'react';
import {Modal, Text, TouchableOpacity, View} from 'react-native';
import {
  restoreStatusBar,
  setTranslucentStatusBar,
} from '@hxa-rn/react-native-modal-translucent';

export default function ManualModal() {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <TouchableOpacity onPress={() => setVisible(true)}>
        <Text>打开 Modal</Text>
      </TouchableOpacity>

      <Modal
        visible={visible}
        transparent={true}
        onShow={async () => {
          await setTranslucentStatusBar(true);
        }}
        onDismiss={async () => {
          await restoreStatusBar();
        }}
        onRequestClose={() => setVisible(false)}>
        <View>
          <Text>Modal 内容</Text>
          <TouchableOpacity onPress={() => setVisible(false)}>
            <Text>关闭</Text>
          </TouchableOpacity>
        </View>
      </Modal>
    </View>
  );
}

需要自行控制调用时机时，可以在 React Native Modal 的 onShow 和 onDismiss 回调中调用导出的异步方法。

接口文档

以下 API 依据 src/index.js、src/index.d.ts、src/specs/v1/NativeModalTranslucent.ts 和 HarmonyOS TurboModule 实现整理。

setTranslucentStatusBar

setTranslucentStatusBar(isTranslucent?: boolean): Promise<void>

设置窗口布局和状态栏背景。

参数	类型	默认值	说明
`isTranslucent`	`boolean`	`true`	为 `true` 时启用全屏布局并将状态栏设置为透明；为 `false` 时恢复模块保存的全屏布局状态，并将状态栏设置为默认黑色不透明值 `#FF000000`。

公开 JS 方法允许省略 isTranslucent，省略时按 true 处理；TurboModule Spec 接收必填的 boolean 参数。原生实现首次调用时保存窗口的全屏布局状态，后续恢复操作使用这份配置。

返回 Promise<void>。当前 JS 封装会捕获原生调用异常，不再向调用方抛出异常，因此不能通过 Promise rejection 判断原生操作是否成功。

restoreStatusBar

restoreStatusBar(): Promise<void>

恢复首次调用 setTranslucentStatusBar 时保存的窗口全屏布局状态，将状态栏设置为默认黑色不透明值 #FF000000，并清除已保存配置。尚未获取窗口或没有已保存配置时，原生实现直接完成，不执行恢复操作。

该方法无参数，返回 Promise<void>。与 setTranslucentStatusBar 一致，当前 JS 封装会捕获原生调用异常。

TranslucentModal

<TranslucentModal {...modalProps} />

TranslucentModal 的类型为 ComponentType<ModalProps>，是 React Native Modal 的 JS 层封装。

属性	类型	默认值	说明
`onShow`	`ModalProps['onShow']`	未声明	先等待 `setTranslucentStatusBar(true)` 完成，再调用传入的回调。
`onDismiss`	`ModalProps['onDismiss']`	未声明	先等待 `restoreStatusBar()` 完成，再调用传入的回调。
其他属性	`ModalProps`	由 React Native `Modal` 声明	通过 `...props` 原样传递给 React Native `Modal`。

快速验证（运行 Example）

前置条件

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

运行步骤

获取开发分支源码：

git clone -b react-native-modal-translucent_dev https://gitcode.com/hxa-rn/react-native-modal-translucent.git

进入仓库根目录：
```
cd react-native-modal-translucent
```
安装根目录依赖：
```
npm i
```
生成供示例工程安装的本地安装包：
```
npm pack --ignore-scripts
```
进入 example 目录：
```
cd example
```
安装示例工程依赖：
```
npm i
```
生成 React Native JavaScript Bundle：
```
npm run dev
```
使用 DevEco Studio 打开 example/harmony，同步依赖，完成签名配置后构建并运行应用。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	以宿主工程配置为准；示例工程使用 `0.72.139`
HarmonyOS SDK	以宿主工程配置为准
Example 工程 `compatibleSdkVersion`	`6.0.1(21)`
Example 工程 `targetSdkVersion`	`6.1.1(24)`
Node.js	`>=18`

使用限制

HarmonyOS 版本不会像上游 Android 版本一样自动覆盖 React Native 内置 Modal；请使用 TranslucentModal，或在 Modal 的 onShow、onDismiss 回调中手动调用接口。
模块只保存一份窗口配置，不为多层嵌套 Modal 维护独立的状态栈；多个 Modal 同时使用时，应由调用方统一管理显示和恢复顺序。
setTranslucentStatusBar(false) 和 restoreStatusBar() 会将状态栏背景恢复为固定的默认黑色不透明值 #FF000000，不会读取调用前的自定义状态栏颜色。
JS 封装会捕获原生方法异常并完成 Promise；如需排查原生失败原因，应查看 HarmonyOS 日志。

系统权限

本库的 HarmonyOS 模块未声明 requestPermissions，不依赖额外的 HarmonyOS 系统权限。

开源 License

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

问题反馈渠道

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

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

Introduction