文档模板：v0.4.2

react-native-modal

本项目基于 react-native-modal 开发。

该第三方库的仓库已迁移至 Gitcode，并支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-modal，版本对应关系如下：

第三方库名称	第三方库版本（npm 地址）	发布信息	支持的 RN 版本	Autolink	编译 API 版本	社区基线版本	源码地址
@react-native-ohos/react-native-modal	~ 14.0.1	Gitcode Releases	0.77.*/0.82.*/0.84.*	否	API12+	14.0.0-rc.1	master
@react-native-ohos/react-native-modal	~ 13.0.2	Gitcode Releases	0.72.*	否	API12+	13.0.1	br_rnoh0.72
@react-native-oh-tpl/react-native-modal	~ 13.0.1-0.0.1@deprecated	Gitcode Releases	0.72.*	否	API12+	13.0.1	sig

简介

react-native-modal 是基于 RN 原生 Modal 封装的增强型模态框组件，提供丰富的进出场动画、手势侧滑关闭、遮罩自定义及滚动适配等扩展能力，API 简洁并兼容多端。

下载安装

进入工程目录，并执行以下命令：

npm

npm install @react-native-ohos/react-native-modal

yarn

yarn add @react-native-ohos/react-native-modal

链接

	是否支持 autolink	RN 框架版本
~14.0.1	否	0.77/0.82/0.84

约束与限制

兼容性

本文档内容已基于以下版本验证通过：

1. RNOH：0.77.18；SDK：HarmonyOS 6.0.0 Release SDK；IDE：DevEco Studio 6.0.0.858；ROM：6.0.0.112；
2. RNOH：0.82.1；SDK：HarmonyOS 6.0.1 Release SDK；IDE：DevEco Studio 6.0.1 Release；ROM：6.0.0.120 SP7；
3. RNOH：0.84.2；SDK：HarmonyOS 6.0.1 Release SDK；IDE：DevEco Studio 26.0.0 Beta1；ROM：6.0.0.120 SP7；

使用示例

以下代码演示了该库的基本使用场景：

import React, {Component} from 'react';
import {Button, StyleSheet, Text, View} from 'react-native';
import Modal from 'react-native-modal';

type Props = {
  onPress: () => any;
};
type State<P> = P & {
  visible: boolean;
};

const DefaultModalContent: React.FC<Props> = props => (
  <View style={styles.content}>
    <Text style={styles.contentTitle}>Hi 👋!</Text>
    <Button testID={'close-button'} onPress={props.onPress} title="Close" />
  </View>
);

abstract class ModalBaseScene<P extends object = {}> extends Component<
  any,
  State<P>
> {
  abstract renderModal(): React.ReactElement<any>;
  // @ts-ignore
  constructor(props, state?: P) {
    super(props);
    // @ts-ignore
    this.state = {
      ...state,
      visible: false,
    };
  }

  open = () => this.setState({visible: true} as any);
  close = () => this.setState({visible: false} as any);
  isVisible = () => this.state.visible;
  public renderButton(): React.ReactElement<any> {
    return (
      <Button testID={'modal-open-button'} onPress={this.open} title="Open" />
    );
  }
  render() {
    return (
      <View style={styles.view}>
        {this.renderButton()}
        {this.renderModal()}
      </View>
    );
  }
}

class DefaultModal extends ModalBaseScene {
  renderModal(): React.ReactElement<any> {
    return (
      <Modal testID={'modal'} isVisible={this.isVisible()}>
        <DefaultModalContent onPress={this.close} />
      </Modal>
    );
  }
}

const styles = StyleSheet.create({
  view: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  content: {
    backgroundColor: 'white',
    padding: 22,
    justifyContent: 'center',
    alignItems: 'center',
    borderRadius: 4,
    borderColor: 'rgba(0, 0, 0, 0.1)',
  },
  contentTitle: {
    fontSize: 20,
    marginBottom: 12,
  },
});

export default DefaultModal;

接口说明

组件

名称	参数类型	必填	平台	OpenHarmony 平台支持	描述
Modal	/	yes	all	yes	Modal 组件

属性

名称	参数类型	默认值	必填	平台	HarmonyOS 平台支持	描述
animationIn	string 或 object	"slideInUp"	no	all	yes	弹窗显示动画
animationInTiming	number	300	no	all	yes	弹窗显示动画时长（毫秒）
animationOut	string 或 object	"slideOutDown"	no	all	yes	弹窗隐藏动画
animationOutTiming	number	300	no	all	yes	弹窗隐藏动画时长（毫秒）
avoidKeyboard	bool	false	no	all	yes	键盘弹出时是否自动上移弹窗
coverScreen	bool	true	no	all	yes	是否使用原生 Modal 组件覆盖整个屏幕
hasBackdrop	bool	true	no	all	yes	是否渲染遮罩层
backdropColor	string	"black"	no	all	yes	遮罩层背景色
backdropOpacity	number	0.70	no	all	yes	弹窗显示时遮罩层的不透明度
backdropTransitionInTiming	number	300	no	all	yes	遮罩层显示动画时长（毫秒）
backdropTransitionOutTiming	number	300	no	all	yes	遮罩层隐藏动画时长（毫秒）
customBackdrop	node	null	no	all	yes	自定义遮罩层元素
children	node	REQUIRED	yes	all	yes	弹窗内容
deviceHeight	number	null	no	all	yes	设备高度（适用于可隐藏导航栏的设备）
deviceWidth	number	null	no	all	yes	设备宽度（适用于可隐藏导航栏的设备）
isVisible	bool	REQUIRED	yes	all	yes	是否显示弹窗
onBackButtonPress	func	() => null	no	Android	yes	Android 设备按下返回键时触发
onBackdropPress	func	() => null	no	all	yes	点击遮罩层时触发
onModalWillHide	func	() => null	no	all	yes	弹窗隐藏动画开始前触发
onModalHide	func	() => null	no	all	yes	弹窗完全隐藏后触发
onModalWillShow	func	() => null	no	all	yes	弹窗显示动画开始前触发
onModalShow	func	() => null	no	all	yes	弹窗完全显示后触发
onSwipeStart	func	() => null	no	all	yes	滑动操作开始时触发
onSwipeMove	func	(percentageShown) => null	no	all	yes	滑动过程中每次事件触发时调用
onSwipeComplete	func	({ swipingDirection }) => null	no	all	yes	达到滑动阈值时触发
onSwipeCancel	func	() => null	no	all	yes	未达到滑动阈值时触发
panResponderThreshold	number	4	no	all	no	触摸响应器开始识别滑动手势的阈值
scrollOffset	number	0	no	all	no	大于 0 时禁用滑动关闭功能，用于实现可滚动内容
scrollOffsetMax	number	0	no	all	yes	用于实现内容可滚动时的越界滚动效果
scrollTo	func	null	no	all	yes	用于实现可滚动弹窗
scrollHorizontal	bool	false	no	all	yes	当滚动视图为横向滚动时设置为 true（保证滚动逻辑正常）
swipeThreshold	number	100	no	all	yes	触发滑动完成回调的滑动阈值
swipeDirection	string 或 array	null	no	all	yes	定义弹窗可滑动的方向，支持 up/down/left/right 单个值或数组组合
useNativeDriver	bool	false	no	all	yes	是否使用原生驱动执行动画
useNativeDriverForBackdrop	bool	null	no	all	yes	遮罩层动画是否使用原生驱动（避免 Android 端闪烁问题）
hideModalContentWhileAnimating	bool	false	no	all	no	动画执行完成前隐藏弹窗内容，以提升性能
propagateSwipe	bool 或 func	false	no	all	no	允许将滑动事件传递给子组件（如弹窗内的滚动视图）
style	any	null	no	all	yes	应用到弹窗的样式
hardwareAccelerated	bool	false	no	android	no	强制为 Modal 独立窗口开启 GPU 硬件加速渲染
statusBarTranslucent	bool	false	no	android	no	Modal 布局延伸至系统状态栏，内容可绘制到状态栏下方，实现沉浸式全屏弹窗
supportedOrientations	string[]	['portrait', 'landscape']	no	ios	no	单独控制当前 Modal 允许旋转的屏幕方向，不受页面全局方向限制
presentationStyle	'fullScreen'|'overFullScreen'|'pageSheet'|'formSheet'	fullScreen	no	ios	no	Modal 的呈现样式
onDismiss	func	() => void	no	ios	no	Modal 关闭动画完全结束后触发回调
onShow	func	() => void	no	all	yes	Modal 弹出动画执行完成且弹窗完全显示后触发
onOrientationChange	func	(orientation) => void	no	all	yes	弹窗显示期间，设备横竖屏切换时触发；弹窗首次渲染时也会执行一次，并返回当前横竖屏状态

API

名称	类型	参数类型	返回值	必填	平台	OpenHarmony 平台支持	描述
open	function	/	/	否	全部	支持	命令式打开弹窗，需要通过 ref 调用（modalRef.current.open()）
close	function	/	/	否	全部	支持	命令式关闭弹窗，需要通过 ref 调用（modalRef.current.close()）

遗留问题

• hideModalContentWhileAnimating 属性未生效，属于上游社区缺陷。
• 三端表现一致，存在滑动冲突问题；在该场景下，scrollOffset、propagateSwipe 和 panResponderThreshold 均不受支持。
• 组件显示和关闭时，框架或 ArkUI 的 modal 中 isVisible 状态切换与动画结束时机存在时序竞争，导致 Modal 视觉上出现闪烁。

其他

无

目录结构

/rntpc_react-native-modal            # 项目根目录
├── src                             # RN 代码（核心库源码）
│    └─ index.ts                    # 入口文件，导出 ReactNativeModal
│    └─ modal.tsx                   # Modal 核心组件实现
│    └─ modal.style.ts              # 动画 / 样式相关
│    └─ types.ts                    # 类型定义（ModalProps、动画、方向等）
│    └─ utils.ts                    # 工具函数
│    └─ global.d.ts                 # 全局类型声明
├── dist                            # 编译产物（发布包入口 dist/index.js）
├── example                         # 示例 Demo
├── package.json                    # 包配置，name: @react-native-ohos/react-native-modal
├── tsconfig.json                   # TS 编译配置
├── buildEnv.sh                     # 构建环境脚本
├── README.md                       # 中文安装使用方法
└── README_en.md                    # 英文安装使用方法                   

贡献代码

在使用过程中如发现任何问题，均可提交 Issue，同时也非常欢迎提交 PR。

开源协议

本项目基于 MIT License，请自由使用并参与开源共建。