@bingtang-rn/faster-image for HarmonyOS

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

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 1.7.2 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/faster-image

使用

import { FasterImageView, clearCache, prefetch } from '@candlefinance/faster-image';

// 渲染图片（支持灰度、圆角、缓存策略、blurhash 占位等）
const style = { width: 200, height: 200 };
const source = {
  transitionDuration: 300,
  cachePolicy: 'discWithCacheControl' as const,
  showActivityIndicator: true,
  grayscale: 1,
  blurhash: 'LFE,@D9F01_4Sg#*0;1S_NIW9F',
  url: 'https://picsum.photos/200/200?random=1',
};

<FasterImageView
  onError={(e) => console.warn(e.nativeEvent.error)}
  onSuccess={(e) => console.log(e.nativeEvent.width, e.nativeEvent.height)}
  style={style}
  source={source}
/>

// 清空缓存
const result = await clearCache();

// 预取图片
await prefetch(['https://picsum.photos/200/200?random=0'], {
  headers: { Authorization: 'Bearer token' },
});

import 时使用原库名 '@candlefinance/faster-image'，RNOH alias 自动映射到鸿蒙包 @bingtang-rn/faster-image。

平台差异：

• transitionDuration：原库 iOS 用秒、Android 用毫秒；鸿蒙端归一化为毫秒（< 1 视为秒 × 1000，默认 100ms）。
• contentPosition：ArkUI 用 ImageFit 对齐变体定位，位置正确；图片小于容器时不放大填充（与原库 Android Matrix.setRectToRect 缩放行为略有差异）。
• priority（iOS only）/ progressiveLoadingEnabled（iOS only）：原库 Android 端也无此特性，鸿蒙端降级为忽略 / 一次性解码，行为对齐 Android。

权限要求：

• 需在 module.json5 声明 ohos.permission.INTERNET（网络下载图片）。normal 权限安装时授予，无需运行时动态申请。
• 磁盘缓存写入应用沙箱 cacheDir 目录，无需额外权限。

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/faster-image": "file:../../node_modules/@bingtang-rn/faster-image/harmony/faster_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/faster-image/src/main/cpp" ./faster_image)

target_link_libraries(rnoh_app PUBLIC faster_image)

4. 注册 Package（C++ 侧）

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

#include "FasterImagePackage.h"

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

5. 注册 Package（ETS 侧）

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

import { FasterImagePackage } from '@bingtang-rn/faster-image/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | FasterImageView (source.url) | 图片 URL | string | — | ✅ 完全支持 | | FasterImageView (source.base64Placeholder) | Base64 占位图 | string | — | ✅ 完全支持 | | FasterImageView (source.blurhash) | Blurhash 占位图 | string | — | ✅ 完全支持 | | FasterImageView (source.thumbhash) | Thumbhash 占位图 | string | — | ✅ 完全支持 | | FasterImageView (source.resizeMode) | 缩放模式 | 'fill'|'contain'|'cover'|'center'|'top'|'bottom' | — | ✅ 完全支持 | | FasterImageView (source.contentPosition) | 内容定位 | 'top'|'bottom'|'left'|'right'|'topLeft'|'topRight'|'bottomLeft'|'bottomRight' | — | ⚠️ 部分支持（位置对齐正确，缩放行为与原库略有差异） | | FasterImageView (source.borderRadius) | 圆角 | number | — | ✅ 完全支持 | | FasterImageView (source.borderTopLeftRadius 等) | 四角独立圆角 | number | — | ✅ 完全支持 | | FasterImageView (source.grayscale) | 灰度滤镜 (0-1) | number | — | ✅ 完全支持 | | FasterImageView (source.colorMatrix) | 颜色矩阵 (4×5) | number[][] | — | ✅ 完全支持 | | FasterImageView (source.cachePolicy) | 缓存策略 | 'memory'|'discWithCacheControl'|'discNoCacheControl'|'memoryAndDisc' | — | ✅ 完全支持 | | FasterImageView (source.transitionDuration) | 淡入动画时长 | number | — | ✅ 完全支持 | | FasterImageView (source.failureImage) | 失败图 | string | — | ✅ 完全支持 | | FasterImageView (source.showActivityIndicator) | 加载指示器 | boolean | — | ✅ 完全支持 | | FasterImageView (source.activityColor) | 指示器颜色 | ColorValue | — | ✅ 完全支持 | | FasterImageView (source.headers) | 请求头 | Record<string,string> | — | ✅ 完全支持 | | FasterImageView (source.allowHardware) | 硬件渲染 | boolean | — | ✅ 完全支持 | | FasterImageView (source.ignoreQueryParamsForCacheKey) | 忽略 query 参数 | boolean | — | ✅ 完全支持 | | FasterImageView (source.priority) | 加载优先级 | 'veryLow'|'low'|'normal'|'high'|'veryHigh' | — | ⚠️ 部分支持（降级为忽略，对齐 Android） | | FasterImageView (source.progressiveLoadingEnabled) | 渐进式加载 | boolean | — | ⚠️ 部分支持（降级为一次性解码，对齐 Android） | | FasterImageView (onSuccess) | 加载成功回调 | — | { width, height, source } | ✅ 完全支持 | | FasterImageView (onError) | 加载失败回调 | — | { error } | ✅ 完全支持 | | clearCache | 清空缓存 | — | Promise<boolean> | ✅ 完全支持 | | prefetch | 预取图片 | sources: string[], options?: { headers? } | Promise<void> | ✅ 完全支持 |

平台差异

• transitionDuration 单位归一化：iOS 用秒（如 0.3），Android 用毫秒（如 300）；鸿蒙端统一为毫秒（< 1 视为秒 × 1000，默认 100ms）。
• contentPosition 缩放：原库 Android 用 Matrix.setRectToRect 缩放后定位；鸿蒙端用 ImageFit.TOP_START 等对齐变体以原始尺寸定位，图片小于容器时不放大填充。位置语义正确，缩放行为略有差异。
• colorMatrix 展平：公开 API 为 number[][]（4×5），JS wrapper 展平为 number[20] 传入 ArkUI ColorFilter。

未实现功能

| API | 原因 | |-----|------| | source.priority | iOS only 特性，原库 Android 无此能力，鸿蒙 @ohos.net.http 无内置请求优先级枚举，降级为忽略 | | source.progressiveLoadingEnabled | iOS only 特性，原库 Android 无此能力，鸿蒙 @ohos.multimedia.image 增量解码与 Nuke 渐进式渲染不等价，降级为一次性解码 | | source.accessible / accessibilityLabel | 原库仅类型声明，无原生实现 |

使用限制

• cachePolicy: 'discWithCacheControl' 的 Cache-Control 过期判断：鸿蒙端简化为命中即用（与 Android Coil CachePolicy.ENABLED 行为一致），不解析 HTTP 过期头。

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