react-native-smart-splash-screen

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

项目介绍

@hxa-rn/react-native-smart-splash-screen 是 react-native-smart-splash-screen 的鸿蒙（OpenHarmony / HarmonyOS，RNOH）适配包，当前版本 2.3.8。

本库含原生实现（HAR + TurboModule）：应用冷启动时在原生层展示全屏启动画面（资源名 splash），JS 侧在首屏就绪后调用 SplashScreen.close(options) 关闭启动屏。支持无动画 / 淡出 / 缩放淡出，以及 duration、delay 配置。

集成指南

npm install @hxa-rn/react-native-smart-splash-screen

业务代码仍按原包名导入（harmony.alias）：

import SplashScreen from 'react-native-smart-splash-screen';

peerDependencies：react-native >= 0.72。

本库需要原生侧 autolinking（C++ Package + ETS Package）。若工程已接入 RNOH Autolink，一般无需手动注册。宿主还需在冷启动时展示启动屏（JS 侧没有 on-demand show API），参考 Example 的 EntryAbility / SplashScreenTurboModule.show(...)，启动图资源放在 entry/src/main/resources/base/media/splash.png。

使用说明

首屏就绪后关闭启动屏：

import SplashScreen from 'react-native-smart-splash-screen';

SplashScreen.close({
  animationType: SplashScreen.animationType.scale,
  duration: 1000,
  delay: 500,
});

立即关闭（无动画，使用默认参数）：

SplashScreen.close();

animationType = none（值为 0）时，delay 会被忽略并立即关闭，与 Android 行为一致。重复调用 close()、启动屏未展示时调用均为空操作，不抛异常。

接口文档

SplashScreen.close(options?)

关闭启动屏。返回值：void。

参数	类型	必填	默认值	说明
options	object	否	{}	关闭配置
options.animationType	number	否	0	0=none 立即关闭；1=fade 淡出；2=scale 缩放淡出。建议用 SplashScreen.animationType
options.duration	number	否	0	动画时长（毫秒）。非正值按 0 处理
options.delay	number	否	0	关闭延迟（毫秒）。animationType=none 时强制为 0

SplashScreen.animationType

由 TurboModule getConstants() 暴露：

键	值	说明
none	0	无动画，立即关闭
fade	1	淡出
scale	2	缩放并淡出

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-smart-splash-screen.git
cd react-native-smart-splash-screen
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-smart-splash-screen@2.3.8，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

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。

约束与限制

• 兼容性：Demo compatibleSdkVersion 为 5.0.1(13)；peerDependencies 要求 react-native >= 0.72。
• 权限：库模块未声明额外系统权限。
• 展示与关闭：启动屏展示由宿主原生层触发；JS 侧唯一可控 API 是 close。
• 平台差异：鸿蒙用子窗口 + ArkUI 页面展示启动屏，与 Android Dialog / iOS loadingView 机制不同，但 JS 调用语义对齐。scale 的缩放比例与 pivot 存在观感差异。
• 启动图资源名需保持 splash，便于复用源平台资源。

开源license

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

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可在 GitCode 反馈：

• https://gitcode.com/hxa-rn/react-native-smart-splash-screen
• https://gitcode.com/hxa-rn/react-native-smart-splash-screen/issues