@bingtang-rn/react-native-blasted-image for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-blasted-image

使用

import BlastedImage, { loadImage } from 'react-native-blasted-image';

// 远程图片
const src = { uri: 'https://example.com/img.png' };
<BlastedImage source={src} width={120} height={120} />

// tintColor + resizeMode
<BlastedImage
  source={src}
  resizeMode="contain"
  tintColor="#FF0000"
  width={100}
  height={100}
/>

// 预加载（带重试）
await loadImage('https://example.com/img.png', false, false, null, null, 3, null);
await BlastedImage.preload([{ uri: 'https://example.com/img.png' }]);

// 清缓存
await BlastedImage.clearMemoryCache();
await BlastedImage.clearDiskCache();
await BlastedImage.clearAllCaches();

import 时使用原库名 'react-native-blasted-image'，而非鸿蒙包名（由 harmony.alias 自动映射）。

平台差异：

• HarmonyOS 端图片缓存由 BlastedImageCache 自建（ArkUI Image 自带缓存不支持自定义 cacheKey），内存缓存为 Map<string, PixelMap>，磁盘缓存为 <cacheDir>/blasted-image/*.bin。
• hybridAssets 本地优先：鸿蒙端从 rawfile/blasted-image/ 读取本地副本，未命中才走网络。需手动将资源拷入该目录（Expo config plugin 不适用于鸿蒙）。
• tintColor 支持 #RGB/#RRGGBB/#AARRGGBB/RRGGBB/命名颜色（black/white/red/...），通过 renderMode(Template) + fillColor 实现。

权限要求：

• 需在 module.json5 声明 ohos.permission.INTERNET（网络图片加载）。

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

target_link_libraries(rnoh_app PUBLIC blasted_image)

4. 注册 Package（C++ 侧）

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

#include "BlastedImagePackage.h"

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

5. 注册 Package（ETS 侧）

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

import { BlastedImagePackage } from '@bingtang-rn/react-native-blasted-image/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | BlastedImage (组件) | 图片组件 | source, resizeMode, tintColor, width, height, isBackground, returnSize, fallbackSource, retries, cacheKeyExtractor, onLoad, onError | — | ✅ 完全支持 | | loadImage | 预加载/缓存远程图片 | imageUrl, skipMemoryCache, hybridAssets, cloudUrl, headers, retries, cacheKey | Promise<{wasRetried}> | ✅ 完全支持 | | preload | 批量预加载 | input: object|array, options | Promise | ✅ 完全支持 | | clearMemoryCache | 清内存缓存 | 无 | Promise | ✅ 完全支持 | | clearDiskCache | 清磁盘缓存 | 无 | Promise | ✅ 完全支持 | | clearAllCaches | 清全部缓存 | 无 | Promise | ✅ 完全支持 | | BlastedEventLoaded | 加载完成事件 | — | {message: string} | ✅ 完全支持 | | BlastedEventClearedMemory | 内存缓存已清事件 | — | {message: string} | ✅ 完全支持 | | BlastedEventClearedDisk | 磁盘缓存已清事件 | — | {message: string} | ✅ 完全支持 | | BlastedEventClearedAll | 全部缓存已清事件 | — | {message: string} | ✅ 完全支持 | | BlastedEventLog | 日志事件 | — | {message: string} | ✅ 完全支持 |

平台差异

• resizeMode="repeat"：原库 Android/iOS 未实现 repeat 分支，鸿蒙端回退为 cover（与原库行为一致）。
• returnSize：依赖 RNOH 的 Image.getSize 实现获取远程图片尺寸。
• BlastedEventLoaded 的 message 格式为 [BlastedImage] (MEMORY|LOCAL|DISK|NETWORK) <url>，与 Android 端一致。

未实现功能

| 功能 | 原因 | |-----|------| | AVIF 格式 | 鸿蒙 Image Kit ImageSource 不支持 AVIF 解码（仅 JPEG/PNG/GIF/WebP/BMP/SVG/ICO/HEIC） | | APNG 格式 | ArkUI 不支持 APNG 动画 | | Expo config plugin | Expo 不支持鸿蒙，hybridAssets 需手动拷入 rawfile/blasted-image/ |

使用限制

• 网络图片加载需声明 ohos.permission.INTERNET。
• HTTP 明文流量默认禁止，加载 http:// 图片需在 module.json5 配置 cleartext。
• hybridAssets 本地资源需手动放入 entry/src/main/resources/rawfile/blasted-image/ 目录。

快速验证（运行 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+

遗留问题

• AVIF/APNG 格式不支持（鸿蒙 Image Kit 无对应解码器）。
• Expo config plugin 不适用于鸿蒙，hybridAssets 需手动拷入 rawfile。

开源协议

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