基于传统 RNSplashScreen 集成的 Lottie 动画启动页组件

classic-lottie-splash-screen

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

项目介绍

@hxa-rn/classic-lottie-splash-screen 是 react-native-lottie-splash-screen 的 React Native 鸿蒙（OpenHarmony / RNOH）适配版本，当前版本 1.1.6。

本库为含原生模块的 TurboModule 插件：鸿蒙端通过全屏子窗口 + @ohos/lottie 渲染 Lottie 启动动画，JS 侧提供 hide() / show() 等 API，隐藏语义对齐 Android/iOS 原库状态机（动画播完且已请求 hide 时才销毁窗口）。

核心能力：

宿主冷启动时在原生层展示 Lottie 启动屏（EntryAbility 调用 SplashScreenTurboModule.show(...)）
JS 调用 SplashScreen.hide() 请求隐藏；动画未播完时等待，播完后自动关闭
启动屏未展示或已关闭时 hide() 安全空操作，不抛异常
支持 Autolinking（harmony.autolinking 已配置）

集成指南

安装

npm install @hxa-rn/classic-lottie-splash-screen

业务代码 import 仍使用原库名（由 harmony.alias 映射）：

import SplashScreen from 'classic-lottie-splash-screen';

peerDependencies：

react-native: >=0.72

Node.js： >=18（以 package.json 的 engines 为准）

Autolinking

本模块已配置 harmony.autolinking（cmakeLibraryTargetName: classic_lottie_splash_screen，ohPackageName: @hxa-rn/classic-lottie-splash-screen）。宿主工程启用 Autolinking 后通常无需手动注册 Package。

若未启用 Autolinking，需在 C++ 与 ETS 两侧注册 ClassicLottieSplashScreenPackage，并在 entry/oh-package.json5 引入 HAR：

"dependencies": {
  "@hxa-rn/classic-lottie-splash-screen": "file:../../node_modules/@hxa-rn/classic-lottie-splash-screen/harmony/classic_lottie_splash_screen.har"
}

执行 ohpm install，并在 entry/src/main/cpp/CMakeLists.txt 链接 classic_lottie_splash_screen 目标。

宿主必做：冷启动展示启动屏

鸿蒙端启动屏展示由宿主原生层完成，JS 仅负责隐藏。在 EntryAbility.onWindowStageCreate 中调用（ArkTS，不是 JS）：

import { SplashScreenTurboModule } from '@hxa-rn/classic-lottie-splash-screen';

SplashScreenTurboModule.show(
  this.context,
  windowStage,
  { lottiePath: 'loading.json', backgroundColor: '#FFFFFF' },
  'pages/SplashScreenPage'
);

还需：

在 entry/src/main/ets/pages/ 创建启动页，并从 HAR 导入 SplashScreenView（Canvas + @ohos/lottie 渲染）
在 entry/src/main/resources/base/profile/main_pages.json 登记 pages/SplashScreenPage
将 Lottie JSON 放入 entry/src/main/resources/rawfile/（如 loading.json）

启动页最小形态：

import { SplashScreenView } from '@hxa-rn/classic-lottie-splash-screen';

@Entry
@Component
struct SplashScreenPage {
  @State demoAnimFinished: boolean = false;

  build() {
    Stack() {
      SplashScreenView({ demoAnimFinished: $demoAnimFinished })
    }
    .width('100%')
    .height('100%')
  }
}

使用说明

应用加载完成后隐藏启动屏

import SplashScreen from 'classic-lottie-splash-screen';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    SplashScreen.hide();
  }, []);

  return null;
}

隐藏语义：

调用 hide() 后置 waiting=true
若 Lottie 动画已播完，启动屏子窗口立即销毁
若动画未播完，启动屏保持显示，待动画 complete 后自动销毁
启动屏未展示或已关闭时，hide() 为安全 no-op

运行期再次展示（JS 兼容）

import SplashScreen from 'classic-lottie-splash-screen';

SplashScreen.show();

标准冷启动流程下启动屏已由宿主 SplashScreenTurboModule.show(...) 创建，此时为安全 no-op；若子窗口已销毁但宿主仍持有 windowStage 引用，可重建启动屏子窗口。

接口文档

以下 API 均通过 TurboModule SplashScreen 暴露，与 src/index.d.ts 一致。

API	说明	参数	返回值
`hide()`	请求隐藏启动屏。动画播完且已请求 hide 时销毁子窗口；动画未播完则等待 complete；未展示/已关闭时 no-op	无	`void`
`show()`	JS 兼容展示方法。已展示时 no-op；已销毁且持有 windowStage 时可重建	无	`void`
`setLoopPlayback(loop)`	设置下次 `show()` 重建子窗口时 Lottie 是否循环播放（循环时 complete 不置位动画结束，供测试/Demo 模拟无结束事件场景）	`loop: boolean`	`void`
`notifyAnimationComplete()`	在循环模拟等场景下，由调用方标记动画结束，配合 `hide()` 的 waiting 状态收回启动屏	无	`void`
`configureDemoOverlay(enabled, buttonsJson)`	配置启动屏底部 Demo 操作栏（`example_auto` 测试工程用；`enabled=false` 或不传有效配置时不展示）	`enabled: boolean`，`buttonsJson: string`（JSON 配置）	`void`
`isAnimationFinished()`	查询 Lottie complete 回调是否已触发	无	`boolean`
`isSplashWindowShowing()`	查询启动屏子窗口是否仍在展示	无	`boolean`
`getLastHideDuringAnimation()`	查询最近一次 `hide()` 调用时动画是否尚未播完；未 hide 过返回 `null`	无	`boolean \| null`（原生以 number 编码三态，JS 层 `index.js` 解码）

宿主原生静态方法（非 JS Spec，集成时使用）：

API	说明
`SplashScreenTurboModule.show(context, windowStage, options, pageUrl)`	冷启动创建全屏子窗口并加载启动页。`options.lottiePath` 为 rawfile 相对路径，`options.backgroundColor` 为十六进制背景色

注意：

本模块（v1.1.6）无自动隐藏、无 forceToCloseByHideMethod 选项；须由业务或宿主在适当时机调用 hide()
setLoopPlayback、notifyAnimationComplete、configureDemoOverlay、isAnimationFinished、isSplashWindowShowing、getLastHideDuringAnimation 主要服务于测试/Demo 场景，生产集成通常只需 hide() / show()

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/classic-lottie-splash-screen.git
cd classic-lottie-splash-screen
git checkout main

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

cd example
npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/classic-lottie-splash-screen@^1.1.6，不再使用本地 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 使用 `react-native@0.72.5` 与 `@react-native-oh/react-native-harmony@0.72.140`（TurboModule 新架构）
HarmonyOS SDK	`example/harmony` 的 `compatibleSdkVersion` 为 `6.0.1(21)`
Node.js	根目录 `engines.node` 为 `>=18`；Example 的 `engines` 要求 `>=20`
权限	HAR `harmony/classic_lottie_splash_screen` 的 `requestPermissions` 为空，无额外系统权限要求
架构	仅支持 TurboModule 新架构；冷启动须在宿主 `EntryAbility` 调用 `SplashScreenTurboModule.show(...)`，并完成启动页、`main_pages.json` 与 rawfile Lottie 资源登记
隐藏语义	无自动隐藏；须由业务调用 `hide()`。动画未播完时等待 complete，播完且已请求 hide 后才销毁子窗口；未展示或已关闭时 `hide()` 为空操作
资源与宿主	Lottie 首帧渲染前可能短暂空白，由 `backgroundColor` 兜底；文件缺失或无效时保持背景色、应用不崩溃。JS `show()` 为兼容方法，依赖宿主持续持有 `windowStage`