@hxa-rn/react-native-turbo-image

本项目基于 react-native-turbo-image 开发，并适配 React Native for OpenHarmony。 如果在使用过程中有任何问题，可以在 GitCode 提交 Issue，我们会及时跟进。

项目介绍

@hxa-rn/react-native-turbo-image 是一个面向 React Native 的高性能图片组件，提供图片加载、显示效果、占位图、加载状态和缓存管理能力。鸿蒙实现支持网络图片与应用资源图片，并提供 GIF 和 APNG 动图加载能力。

• 支持网络图片、resource:// 应用资源图片和自定义请求头。
• 支持 contain、cover、stretch、center 图片缩放模式。
• 支持 BlurHash、ThumbHash、内存缓存占位图和加载指示器。
• 支持淡入、圆形裁剪、模糊、单色、缩放和着色效果。
• 支持 URL 缓存、内存与磁盘数据缓存，以及缓存预加载、释放和清理。
• 支持加载开始、进度、成功、失败和完成事件。

集成指南

安装

在 React Native 工程根目录执行：

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

宿主工程需使用 React Native >=0.72。

Autolinking

本库支持 Autolinking，安装依赖后由宿主工程自动接入，无需手动注册。

导入

import TurboImage, {
  type CachePolicy,
  type Source,
  type TurboImageProps,
} from '@hxa-rn/react-native-turbo-image';

使用说明

基础用法

import React from 'react';
import {StyleSheet, View} from 'react-native';
import TurboImage from '@hxa-rn/react-native-turbo-image';

export default function App() {
  return (
    <View style={styles.container}>
      <TurboImage
        //填写一个具体的网络图片地址
        source={{uri: 'https://picsum.photos/800/600'}}
        style={styles.image}
        resizeMode="cover"
        cachePolicy="urlCache"
        fadeDuration={250}
        onSuccess={event => {
          console.log(
            '图片尺寸：',
            event.nativeEvent.width,
            event.nativeEvent.height,
          );
        }}
        onFailure={event => {
          console.warn(event.nativeEvent.error);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {flex: 1},
  image: {width: '100%', height: 240},
});

source.uri 支持网络地址和 resource://文件名 形式的应用资源路径。placeholder 仅能同时指定 blurhash、thumbhash、memoryCacheKey 中的一项；启用 showPlaceholderOnFailure 时必须提供 placeholder。

缓存管理

import TurboImage from '@hxa-rn/react-native-turbo-image';
//填写一个具体的网络图片地址
const source = {uri: 'https://picsum.photos/800/600'};

const prefetched = await TurboImage.prefetch([source], 'dataCache');
await TurboImage.dispose([source]);
await TurboImage.clearMemoryCache();
await TurboImage.clearDiskCache();

urlCache 使用系统 HTTP 响应缓存；dataCache 使用库提供的内存与磁盘缓存。prefetch 的默认缓存策略为 urlCache。

接口文档

以下 API 依据 src/index.tsx、src/types.ts 和 src/specs/v1/TurboImageViewNativeComponent.ts 中的入口导出与类型定义整理。

TurboImage

默认导出的图片组件，同时挂载缓存管理静态方法。组件 Props 继承 React Native 的 AccessibilityProps 和 ViewProps。

属性	类型	默认值	说明
source	Source	必填	图片来源，包含 uri，可选 headers 和 cacheKey。
style	StyleProp<ViewStyle>	必填	图片容器样式。
reloadToken	number	未声明	值变化时触发图片重新加载。
resizeMode	'contain' | 'cover' | 'stretch' | 'center'	'contain'	图片缩放模式。
indicator	Indicator	未声明	加载指示器，可配置 style 和 color。
placeholder	Placeholder	未声明	BlurHash、ThumbHash 或内存缓存占位图，仅能指定一种。
showPlaceholderOnFailure	boolean	false	加载失败时是否继续显示占位图；启用时必须提供 placeholder。
fadeDuration	number	无占位图时 100，有占位图时 0	图片淡入时长，单位为毫秒。
rounded	boolean	false	是否使用圆形裁剪。
blur	number	未声明	模糊半径。
monochrome	number | ColorValue	未声明	单色滤镜颜色。
resize	number	未声明	按目标宽度等比例缩放图片，单位为 dp：像素宽度 = resize 值 × 屏幕密度（如 3 倍密度下 resize={50} 得到 150 px 宽），高度 = 像素宽度 × 源图高度 ÷ 源图宽度，目标宽度超过源图宽度时不放大，缩放发生在解码阶段。只改变位图分辨率与清晰度，不改变图片的显示尺寸（显示尺寸由 style 宽高与 resizeMode 决定）。
tint	number | ColorValue	未声明	图片着色颜色。
cachePolicy	'urlCache' | 'dataCache'	'urlCache'	缓存策略。
enableLiveTextInteraction	boolean	未声明	iOS Live Text 配置；鸿蒙侧不使用。
isProgressiveImageRenderingEnabled	boolean	未声明	iOS 渐进式渲染配置；鸿蒙侧不使用。
allowHardware	boolean	true	Android 硬件图片配置；鸿蒙侧不使用。
format	'svg' | 'gif' | 'apng'	未声明	显式指定图片格式。鸿蒙侧对 APNG 使用自定义解码；svg 按实际显示尺寸（或 resize 指定宽度）光栅化，避免按 SVG 自带尺寸出图后拉伸发虚。
onStart	(event: NativeSyntheticEvent<Start>) => void	未声明	图片开始加载时触发，返回任务状态。
onProgress	(event: NativeSyntheticEvent<Progress>) => void	未声明	加载进度变化时触发，返回已完成和总字节数。
onSuccess	(event: NativeSyntheticEvent<Success>) => void	未声明	加载成功时触发，返回图片宽度、高度和来源。
onFailure	(event: NativeSyntheticEvent<Failure>) => void	未声明	加载失败时触发，返回错误信息。
onCompletion	(event: NativeSyntheticEvent<Completion>) => void	未声明	加载结束时触发，返回任务状态。

Source

属性	类型	默认值	说明
uri	string	必填	网络图片地址或 resource://文件名 应用资源路径。
headers	Record<string, string>	未声明	网络请求头。
cacheKey	string	未声明	自定义缓存键；未提供时使用 uri。

Indicator

属性	类型	默认值	说明
style	'large' | 'medium'	'medium'	加载指示器尺寸。
color	number | ColorValue	未声明	加载指示器颜色。

Placeholder

属性	类型	默认值	说明
blurhash	string	未声明	BlurHash 编码字符串。
thumbhash	string	未声明	ThumbHash 编码字符串。
memoryCacheKey	string	未声明	从内存缓存复用图片的缓存键。

静态方法

方法	参数	返回值	说明
TurboImage.prefetch	sources: Source[], cachePolicy?: CachePolicy	Promise<boolean>	预加载图片；默认使用 urlCache。
TurboImage.dispose	sources: Source[]	Promise<void>	释放指定来源对应的缓存资源。
TurboImage.clearMemoryCache	无	Promise<void>	清空内存缓存。
TurboImage.clearDiskCache	无	Promise<void>	清空磁盘缓存及 HTTP 响应缓存。

导出类型

本库还导出 Source、CachePolicy、Format、Start、Progress、Success、Failure、Completion、ResizeMode、Indicator、IndicatorStyle 和 TurboImageProps 类型。

快速验证（运行 Example）

前置条件

依赖	版本要求
Node.js	>=20
React Native for OpenHarmony	0.72.139
HarmonyOS SDK	API 21+

运行步骤

1. 获取开发分支源码。

   git clone -b react-native-turbo-image_dev https://gitcode.com/hxa-rn/react-native-turbo-image
   

2. 进入仓库根目录。

   cd react-native-turbo-image
   

3. 安装根目录依赖。

   npm i
   

4. 生成供示例工程安装的本地安装包。

   npm pack
   

5. 进入 example 目录。

   cd example
   

6. 安装示例工程依赖。

   npm install --legacy-peer-deps
   

7. 生成 React Native JavaScript Bundle。

   npm run dev
   

8. 使用 DevEco Studio 打开 example/harmony，同步依赖、完成签名配置后构建并运行 entry 模块。

约束与限制

兼容性

依赖	要求
React Native for OpenHarmony	>=0.72，Example 使用 0.72.139
HarmonyOS SDK	API 21+
Example 工程 compatibleSdkVersion	6.0.1(21)
Example 工程 targetSdkVersion	6.1.1(24)
Node.js	>=18

使用限制

• placeholder 只能配置 blurhash、thumbhash、memoryCacheKey 中的一项，否则组件会抛出错误。
• showPlaceholderOnFailure 为 true 时必须同时提供 placeholder。
• 鸿蒙侧不使用仅适用于 iOS/Android 的 enableLiveTextInteraction、isProgressiveImageRenderingEnabled 和 allowHardware 配置。
• 鸿蒙自定义 APNG 解码支持 8-bit RGBA、非隔行 APNG；不符合要求的 APNG 会触发 onFailure。
• blur、monochrome 和 tint 依赖 HarmonyOS 图像效果实现，视觉结果可能与 iOS、Android 存在差异。

系统权限

网络图片加载依赖 ohos.permission.INTERNET，本库的 HarmonyOS 模块已声明该权限。

开源 License

本项目采用 MIT License，与上游项目保持一致。

问题反馈渠道

如在使用过程中遇到问题，请在 GitCode 提交Issue，我们会及时跟进。

• 提交问题时建议附上项目版本、RN 版本、OpenHarmony SDK/API 版本、DevEco Studio 版本、设备信息、复现步骤及相关日志。
• 涉及签名、账号、密钥或用户数据时，请勿在 Issue 中上传敏感信息；可按组织安全流程提交脱敏日志。