react-native-splash-view

本项目基于 react-native-splash-view 开发。如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。

项目介绍

react-native-splash-view 为 React Native 应用提供轻量级启动闪屏（Splash Screen）能力。鸿蒙适配包 @hxa-rn/react-native-splash-view（当前版本 0.0.21-beta.1）基于 TurboModule 实现，包含 JS 封装层与原生 HAR（harmony/splash_view/）。

核心能力：

• JS 侧调用 showSplash() 展示全屏闪屏；
• JS 侧调用 hideSplash() 以淡出动画关闭闪屏并释放窗口；
• 宿主工程可在 RN 加载前于原生层预展示闪屏（EntryAbility.onWindowStageCreate 集成）。

业务代码仍通过原库名导入：import { showSplash, hideSplash } from 'react-native-splash-view'。

集成指南

安装

npm install @hxa-rn/react-native-splash-view

导入说明

package.json 中配置了 harmony.alias: "react-native-splash-view"，业务侧继续使用：

import { showSplash, hideSplash } from 'react-native-splash-view';

依赖要求

| 依赖 | 版本要求 | |------|----------| | react-native | >= 0.72 | | react | * | | Node.js | >= 18 |

Autolink

本模块支持 Autolink（harmony.autolinking 已配置 SplashViewPackage 的 ETS / C++ 注册）。工程已接入 RNOH Autolink 时，通常无需手动注册 Package。

若 Autolink 未生效，可按以下步骤手动集成：

1. 引入原生依赖

在 entry/oh-package.json5 添加：

"dependencies": {
  "@hxa-rn/react-native-splash-view": "file:../../node_modules/@hxa-rn/react-native-splash-view/harmony/splash_view.har"
}

执行 ohpm install。

2. 配置 CMakeLists

在 entry/src/main/cpp/CMakeLists.txt 添加：

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

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-splash-view/src/main/cpp" ./splash_view)

target_link_libraries(rnoh_app PUBLIC splash_view)

3. 注册 Package

ETS 侧 SplashViewPackage 为包默认导出。在 RNPackagesFactory.ets：

import SplashViewPackage from '@hxa-rn/react-native-splash-view';

new SplashViewPackage(ctx)

C++ 侧在 PackageProvider.cpp：

#include "SplashViewPackage.h"

std::make_shared<SplashViewPackage>(ctx)

4. 宿主闪屏页集成（必需）

在 EntryAbility.onWindowStageCreate 中、super.onWindowStageCreate 之前调用（windowStage 为该回调参数）：

import { SplashViewTurboModule } from '@hxa-rn/react-native-splash-view';

SplashViewTurboModule.showSplashView(windowStage, 'pages/SplashViewPage');

并创建嵌入 SplashViewContent 的启动页（参考本仓库 example/harmony/entry/src/main/ets/pages/SplashViewPage.ets）。该步骤用于存储 windowStage，JS 侧 showSplash() 方可创建全屏子窗口；冷启动时也可在此预展示闪屏。

使用说明

展示与关闭闪屏

import { showSplash, hideSplash } from 'react-native-splash-view';

// 展示全屏闪屏（覆盖整个应用界面，置顶显示）
showSplash();

// 业务就绪后再关闭。子窗口创建是异步的，不要在同一同步调用栈里立刻 hideSplash()，
// 否则窗口尚未建立，hide 会空操作。
setTimeout(() => {
  hideSplash();
}, 2000);

典型场景

冷启动预展示 + RN 首帧后关闭

宿主在 EntryAbility.onWindowStageCreate 预展示闪屏；RN 首帧就绪后在 JS 中调用 hideSplash()：

import { useEffect } from 'react';
import { hideSplash } from 'react-native-splash-view';

useEffect(() => {
  hideSplash();
}, []);

仅 JS 侧按需展示

确认宿主已集成 showSplashView 后，在业务逻辑中调用 showSplash() / hideSplash() 即可。

行为说明

• showSplash()：复用宿主存储的 windowStage 异步创建全屏子窗口；闪屏已在展示时（含原生预展示）安全忽略。
• hideSplash()：在启动页 UIContext 上执行约 0.1s 延时 + 0.3s 淡出动画，完成后销毁子窗口；闪屏未展示或已关闭时为空操作。
• 若宿主未集成 showSplashView，showSplash() 会安全返回并打印告警，不会崩溃。
• showSplash() 与 hideSplash() 不要在同一同步调用栈中连调：创建子窗口未完成时，hideSplash() 会因窗口尚未建立而空操作。

接口文档

模块对外暴露 TurboModule SplashView，JS 侧通过 showSplash / hideSplash 两个函数调用。无常量、无事件。

| API | 签名 | 说明 | 参数 | 返回值 | |-----|------|------|------|--------| | showSplash | showSplash(): void | 展示全屏闪屏；已在展示时安全忽略 | 无 | void | | hideSplash | hideSplash(): void | 隐藏闪屏（淡出动画后释放窗口）；未展示时安全空操作 | 无 | void |

平台差异

• 鸿蒙采用「全屏子窗口 + ArkUI 启动页」展示闪屏，与 Android Dialog / iOS 独立 UIWindow 机制不同，但 JS 调用语义一致。
• 闪屏 UI 内容由宿主启动页（如 SplashViewPage）决定，需自行嵌入 SplashViewContent 或自定义布局。
• 原生预展示入口为 SplashViewTurboModule.showSplashView(windowStage, pageUrl)，不属于 JS 公开契约，但推荐在 EntryAbility 中集成。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18（运行 Example 建议 >= 20，见 example/package.json） | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 13+（example/harmony 的 compatibleSdkVersion 为 5.0.1(13)） |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-splash-view.git
cd react-native-splash-view
git checkout br_rnoh0.72

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

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 Package 注册、Metro alias 与 HAR 依赖，无需手动 Link。编 HAP 前必须先执行 npm run dev。

约束与限制

| 项目 | 说明 | | ---- | ---- | | React Native / RNOH | 对等依赖 react-native >= 0.72。Example 使用 [email protected] 与 @react-native-oh/[email protected]（TurboModule 新架构） | | HarmonyOS SDK | example/harmony 的 compatibleSdkVersion 为 5.0.1(13) | | Node.js | 根目录 engines.node 为 >=18 | | 权限 | 库 HAR requestPermissions 为空，无额外系统权限 | | 架构 | 仅支持 TurboModule 新架构，不支持旧架构 Interop Layer | | 宿主预展示 | showSplash() 依赖宿主先调用 SplashViewTurboModule.showSplashView 存储 windowStage，否则无法创建闪屏窗口 | | 重复调用 | 重复调用 showSplash() / hideSplash() 均为安全操作，不会产生异常 |

开源license

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

问题反馈渠道

如在集成或使用过程中遇到问题，可通过以下渠道反馈：

• AtomGit / GitCode Issue：https://gitcode.com/hxa-rn/react-native-splash-view/issues
• 仓库地址：https://gitcode.com/hxa-rn/react-native-splash-view