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.0-beta.1。本包含原生实现（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 br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 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