react-native-fast-image

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

项目介绍

@hxa-rn/react-native-fast-image 是 @d11/react-native-fast-image v8.13.0 的鸿蒙（OpenHarmony）适配包，提供高性能图片组件，作为 RN 内置 Image 的替代方案。

当前版本：8.13.3。本包含原生实现（TurboModule FastImageViewModule + Fabric 组件 FastImageView），在鸿蒙端用 ImageKit + 自建内存/磁盘缓存替代 Android Glide / iOS SDWebImage。

核心能力：

• 远程 / 本地 / data: base64 图片加载与显示
• immutable / web / cacheOnly 缓存策略，以及 preload / clearMemoryCache / clearDiskCache
• resizeMode、defaultSource、blurRadius、tintColor、transition
• onLoadStart / onProgress / onLoad / onError / onLoadEnd 五个加载事件
• JPEG / PNG / GIF / WebP；SVG 在系统支持时显示；AVIF / APNG 触发 onError 优雅降级

集成指南

npm install @hxa-rn/react-native-fast-image

peer 依赖：react、react-native（>=0.72）。Node >=18。

工程已配置 harmony.alias 时，业务代码仍从原包名导入：

import FastImage from '@d11/react-native-fast-image';

RNOH CLI 会把 '@d11/react-native-fast-image' 重定向到 @hxa-rn/react-native-fast-image。

本模块支持 Autolink。如需手动注册：

1. 在 entry 的 oh-package.json5 依赖 HAR：@hxa-rn/react-native-fast-image。
2. C++ PackageProvider / RNOHPackagesFactory.h 注册 FastImagePackage。
3. ETS RNOHPackagesFactory.ets 注册 new FastImagePackage(ctx)。

空数组注册会导致组件不渲染、TurboModule 找不到。

使用说明

import React from 'react';
import FastImage from '@d11/react-native-fast-image';

export function Demo() {
  return (
    <FastImage
      style={{width: 200, height: 200}}
      source={{
        uri: 'https://picsum.photos/id/1015/400/400',
        headers: {Authorization: 'some-token'},
        priority: FastImage.priority.normal,
        cache: FastImage.cacheControl.immutable,
      }}
      resizeMode={FastImage.resizeMode.cover}
      transition={FastImage.transition.fade}
      onLoadStart={() => {}}
      onProgress={e => {
        const {loaded, total} = e.nativeEvent;
      }}
      onLoad={e => {
        const {width, height} = e.nativeEvent;
      }}
      onError={e => {
        const {error} = e.nativeEvent;
      }}
      onLoadEnd={() => {}}
    />
  );
}

export async function warmAndClearCache() {
  FastImage.preload([{uri: 'https://picsum.photos/id/1015/400/400'}]);
  await FastImage.clearMemoryCache();
  await FastImage.clearDiskCache();
}

可选：用 defaultSource={require('./placeholder.png')} 指定本地占位图（需自行提供该资源）。

接口文档

组件 Props

名称	类型	默认值	说明
source	{ uri?, headers?, priority?, cache? } 或 require()	—	图片源
defaultSource	本地资源	—	加载中/失败占位图
resizeMode	'contain' | 'cover' | 'stretch' | 'center'	'cover'	缩放模式
tintColor	ColorValue	—	非透明像素染色；SVG 用 fillColor，栅格图用 colorFilter
blurRadius	number	0	高斯模糊半径
transition	'fade' | 'none'	'none'	加载完成过渡
fallback	boolean	false	回退到 RN Image（JS 层）
children	ReactNode	—	叠在图片上的子节点

source.priority：'low' \| 'normal' \| 'high'（默认 normal）。 source.cache：'immutable' \| 'web' \| 'cacheOnly'（默认 immutable）。

事件

名称	载荷	说明
onLoadStart	{}	开始加载
onProgress	{ loaded, total }	下载进度（约 0.5% 粒度）
onLoad	{ width, height }	加载成功
onError	{ error }	加载失败
onLoadEnd	{}	结束（成功/失败均触发）

静态方法与常量

名称	签名 / 取值	说明
FastImage.preload	(sources: Source[]) => void	预下载写入缓存，不显示
FastImage.clearMemoryCache	() => Promise<void>	清空内存缓存
FastImage.clearDiskCache	() => Promise<void>	清空磁盘缓存
FastImage.resizeMode	contain / cover / stretch / center	缩放常量
FastImage.priority	low / normal / high	优先级常量
FastImage.cacheControl	immutable / web / cacheOnly	缓存策略常量
FastImage.transition	fade / none	过渡常量

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>= 18
DevEco Studio	5.0+ / 6.0+
HarmonyOS SDK	API 12+

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-fast-image.git
cd react-native-fast-image
git checkout main

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-fast-image@8.13.3，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

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。

约束与限制

项	说明
React Native / RNOH	0.72+（仅新架构 TurboModule + Fabric）
HarmonyOS SDK	compatibleSdkVersion 5.0.1(13)（API 13+）
权限	库模块声明 ohos.permission.INTERNET（system_grant，无需运行时申请）
AVIF	ImageKit / ArkUI Image 无解码器，加载时 onError + onLoadEnd，不崩溃
APNG	ArkUI Image 不支持 apng，加载时 onError 降级
tintColor	SVG 使用 fillColor；栅格图使用 colorFilter（SRC_IN）
GIF / WebP 动图	以 file:// 路径喂 ArkUI Image 播放，依赖节点可见
priority	映射为 @ohos.net.http 优先级数值（low=1 / normal=500 / high=1000），非严格抢占

开源license

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

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可通过 GitCode 仓库反馈：

• https://gitcode.com/hxa-rn/react-native-fast-image
• https://gitcode.com/hxa-rn/react-native-fast-image/issues