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.5-beta.1。

本库为含原生模块的 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'
);

还需：

1. 在 entry/src/main/ets/pages/ 创建启动页，并从 HAR 导入 SplashScreenView（Canvas + @ohos/lottie 渲染）
2. 在 entry/src/main/resources/base/profile/main_pages.json 登记 pages/SplashScreenPage
3. 将 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.5-beta.1）无自动隐藏、无 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 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 为 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 |

开源license

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

问题反馈渠道

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

• AtomGit Issue（抬头推荐渠道）
• GitCode 仓库：https://gitcode.com/hxa-rn/classic-lottie-splash-screen
• GitCode Issue：https://gitcode.com/hxa-rn/classic-lottie-splash-screen/issues