react-native-modal-translucent

本项目基于 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 的回调中手动控制状态栏。

手动控制 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+ |

运行步骤

1. 获取开发分支源码：

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

2. 进入仓库根目录：

   cd react-native-modal-translucent

3. 安装根目录依赖：

   npm i

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

   npm pack --ignore-scripts

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 | 以宿主工程配置为准 | | 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 中上传敏感信息；可按组织安全流程提交脱敏日志。