@bingtang-rn/react-native-loader-kit for HarmonyOS

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

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 4.1.0 | 4.1.0 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-loader-kit

使用

import { LoaderKitView } from 'react-native-loader-kit';

// Basic usage
<LoaderKitView
  name="BallPulse"
  color="blue"
  animationSpeedMultiplier={1.0}
  style={styles.loader}
/>

// Switch animation by name (32 types available)
<LoaderKitView name="CircleStrokeSpin" color="#ff0000" />

// Speed up (duration = baseDuration / speed)
<LoaderKitView name="BallGridPulse" color="green" animationSpeedMultiplier={2.0} />

import 时使用原库名 'react-native-loader-kit'，而非鸿蒙包名。RNOH alias 会自动重定向到 @bingtang-rn/react-native-loader-kit。

平台差异：

• HarmonyOS 支持 32 种动画（含原 iOS 专属 BallRotateChase 和 CircleStrokeSpin），与 iOS 对齐。
• SquareSpin / TriangleSkewSpin 的 3D 翻转用 scaleX/scaleY + rotate 近似（Canvas 2D 无 3D 透视变换），视觉接近但不完全等价。
• AudioEqualizer 用逐帧高度插值替代 iOS path 动画，视觉效果等价。

权限要求：

• 无需任何系统权限。纯 Canvas 绘制 + setInterval 动画，不涉及网络、文件、传感器等。

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-loader-kit": "file:../../node_modules/@bingtang-rn/react-native-loader-kit/harmony/loader_kit.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-loader-kit/src/main/cpp" ./loader_kit)

target_link_libraries(rnoh_app PUBLIC loader_kit)

4. 注册 Package（C++ 侧）

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

#include "LoaderKitPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { LoaderKitPackage } from '@bingtang-rn/react-native-loader-kit/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | LoaderKitView | Fabric 加载动画组件 | name: string, color?: ColorValue, animationSpeedMultiplier?: number | — | ✅ 完全支持 | | name | 动画指示器名称（32 种） | IndicatorName | — | ✅ 完全支持 | | color | 动画图形颜色 | ColorValue | — | ✅ 完全支持 | | animationSpeedMultiplier | 动画速度倍率（默认 1.0） | number | — | ✅ 完全支持 | | COMMON_INDICATORS | 通用动画名常量（30 种） | — | readonly IndicatorName[] | ✅ 完全支持 | | IOS_ONLY_INDICATORS | iOS 专属动画名常量（2 种） | — | readonly IndicatorName[] | ✅ 完全支持 | | ALL_INDICATORS | 全部动画名常量（32 种） | — | readonly IndicatorName[] | ✅ 完全支持 | | isIndicatorAvailableOnPlatform | 检查动画在平台是否可用 | (indicator, platform: 'ios'\|'android'\|'harmony') | boolean | ✅ 完全支持 | | getAvailableIndicators | 获取平台可用动画列表 | (platform: 'ios'\|'android'\|'harmony') | readonly IndicatorName[] | ✅ 完全支持 |

平台差异

• SquareSpin / TriangleSkewSpin：Canvas 2D 无 3D 透视变换，用 scaleX/scaleY + rotate 近似 3D 翻转效果，视觉接近但无透视变形。
• AudioEqualizer：iOS 使用 path 关键帧动画，鸿蒙端改为逐帧高度插值绘制 rounded rect，视觉效果等价。

使用限制

• 无系统权限要求。
• Example 中 32 个动画同时运行时各有独立 Canvas + setInterval，大量并发可能影响帧率。

快速验证（运行 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 文件。