@bingtang-rn/react-native-modalfy for HarmonyOS

本项目基于 react-native-modalfy 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 3.7.0 | 0.72+ | 否 | API17+ |

安装

npm install @bingtang-rn/react-native-modalfy

使用

import { ModalProvider, createModalStack, useModal } from 'react-native-modalfy';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

const stack = createModalStack({
  MyModal: MyModalComponent,
});

function App() {
  const { openModal, closeModal, currentModal } = useModal();

  return (
    <GestureHandlerRootView style={styles.container}>
      <ModalProvider stack={stack}>
        <Button onPress={() => openModal('MyModal', { title: 'Hello' })} title="Open" />
      </ModalProvider>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});

import 时使用原库名 'react-native-modalfy'，而非鸿蒙包名。

平台差异：

• HarmonyOS 上 Fling 手势（滑动关闭模态）依赖 @react-native-oh-tpl/react-native-gesture-handler，真机行为需实际设备验证
• Platform.OS === 'web' 分支在鸿蒙端不执行，Web 专属逻辑（滚动锁定等）自动跳过

权限要求：

• 无

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 否 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-modalfy": "file:../../node_modules/@bingtang-rn/react-native-modalfy/harmony/modalfy.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-modalfy/src/main/cpp" ./modalfy)

target_link_libraries(rnoh_app PUBLIC modalfy)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "ModalfyPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<ModalfyPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { ModalfyPackage } from '@bingtang-rn/react-native-modalfy/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | createModalStack | 创建模态栈配置 | config: ModalStackConfig, defaultOptions?: ModalOptions | ModalStack | ✅ 完全支持 | | ModalProvider | 模态栈容器组件 | stack: ModalStack, children: ReactNode | ReactElement | ✅ 完全支持 | | useModal | Hook 获取模态 API | 无 | UsableModalProp | ✅ 完全支持 | | withModal | HOC 获取模态 API | Component | Component | ✅ 完全支持 | | modalfy | Context 外部调用 API | 无 | UsableModalProp | ✅ 完全支持 | | openModal | 打开模态 | name, params?, callback? | void | ✅ 完全支持 | | closeModal | 关闭模态 | name?, callback? | void | ✅ 完全支持 | | closeModals | 关闭同名所有实例 | name, callback? | boolean | ✅ 完全支持 | | closeAllModals | 关闭所有模态 | callback? | void | ✅ 完全支持 | | currentModal | 当前栈顶模态名称 | 无 | string | null | ✅ 完全支持 | | getParam | 获取传入参数 | paramName, defaultValue? | any | ✅ 完全支持 | | addListener | 监听 onAnimate/onClose | eventName, callback | { remove() } | ✅ 完全支持 | | removeAllListeners | 移除所有监听器 | 无 | void | ✅ 完全支持 | | setModalOptions | 动态更新模态选项 | options: ModalOptions | void | ✅ 完全支持 | | params | 访问传入参数 | 无 | object | ✅ 完全支持 | | position | 模态垂直定位 | 'center' | 'top' | 'bottom' | — | ✅ 完全支持 | | animationIn/animationOut | 自定义动画函数 | (value, toValue, callback?) => void | — | ✅ 完全支持 | | animateInConfig/animateOutConfig | 动画配置 | { duration, easing } | — | ✅ 完全支持 | | backBehavior | 返回键行为 | 'pop' | 'clear' | 'none' | — | ✅ 完全支持 | | backdropColor/backdropOpacity | 背景遮罩 | string / number | — | ✅ 完全支持 | | backdropPosition | 背景遮罩位置 | 'root' | 'belowLatest' | — | ✅ 完全支持 | | disableFlingGesture | 禁用滑动关闭 | boolean | — | ✅ 完全支持 | | pointerEventsBehavior | 触摸事件行为 | 'auto' | 'none' | 'current-modal-only' | 'current-modal-none' | — | ✅ 完全支持 | | transitionOptions | 过渡样式函数 | (animatedValue) => Style | — | ✅ 完全支持 | | containerStyle | 模态容器样式 | ViewStyle | — | ✅ 完全支持 | | stackContainerStyle | 栈容器样式 | ViewStyle | (opacity) => ViewStyle | — | ✅ 完全支持 |

平台差异

• Fling 手势（Gesture.Fling()）用于模态滑动关闭，在鸿蒙端依赖 @react-native-oh-tpl/react-native-gesture-handler，构建已验证通过，真机运行时行为需实际设备测试
• Animated.timing 的 useNativeDriver: true 在鸿蒙端支持 translateY/opacity 等属性
• BackHandler.addEventListener('hardwareBackPress') 在鸿蒙端支持硬件返回键监听

未实现功能

无

使用限制

• 必须包裹在 GestureHandlerRootView 中（与原库一致）
• Fling 手势仅在 position 为 'top' 或 'bottom' 时生效（与原库一致）

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

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

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 MIT 协议，详见 LICENSE 文件。