rntpc_react-native-fast-image:基于 React Native 的图片加载优化库项目

用户可用于在 React Native 应用中高效加载和管理图片,提升图片加载性能与用户体验。该项目支持多种图片加载事件监听、缩放模式设置及缓存管理,适配不同 RN 版本,提供便捷的安装与集成方式。【此简介由AI生成】

Branch6Tags3

模板版本:v0.4.0

react-native-fast-image

Supported platforms License

本项目基于react-native-fast-image 开发

该第三方库的仓库已迁移至 Gitcode,且支持直接从 npm 下载,新的包名为:@react-native-ohos/react-native-fast-image 版本所属关系如下

三方库名称 三方库版本 发布信息 支持RN版本 Autolink 编译API版本 社区基线版本 npm地址
@react-native-ohos/react-native-fast-image ~8.8.0 Gitcode Releases 0.82.* 是 API12+ 8.6.3 Npm Address
@react-native-ohos/react-native-fast-image ~8.7.0 Gitcode Releases 0.77.* 否 API12+ 8.6.3 Npm Address
@react-native-ohos/react-native-fast-image ~8.6.4 Gitcode Releases 0.72.* 是 API12+ 8.6.3 Npm Address
@react-native-oh-tpl/react-native-fast-image <= 8.6.3-0.4.17@deprecated Github Releases 0.72.* 否 API12+ 8.6.3 Npm Address

1.安装与使用

进入到工程目录并输入以下命令:

npm

npm install @react-native-ohos/react-native-fast-image

yarn

yarn add @react-native-ohos/react-native-fast-image

下面的代码展示了这个库的基本使用场景:

使用时 import 的库名不变。

import React from "react";
import { StyleSheet, View, ScrollView } from "react-native";
import FastImage, {
  ResizeMode,
  OnLoadEvent,
  OnProgressEvent,
} from "react-native-fast-image";

export const FastImageDemo = () => {
  return (
    <ScrollView>
      <View>
        <FastImage
          style={styles.image}
          source={{
            uri: "https://res8.vmallres.com/pimages/uomcdn/CN/pms/202205/gbom/6941487259298/428_428_D7BFF22D4678EB68440F914B352214C4mp_tds.png",
          }}
          resizeMode={FastImage.resizeMode.contain}
          onLoadStart={() => {
            console.log("onLoadStart: success");
          }}
          onProgress={(e: OnProgressEvent) => {
            console.log(
              "onProgress: success loaded=" +
                e.nativeEvent.loaded +
                " total=" +
                e.nativeEvent.total
            );
          }}
          onLoad={(e: OnLoadEvent) => {
            console.log(
              "onLoad: success width=" +
                e.nativeEvent.width +
                " height=" +
                e.nativeEvent.height
            );
          }}
          onError={() => {
            console.log("onError: success");
          }}
          onLoadEnd={() => {
            console.log("onLoadEnd: success");
          }}
        />
      </View>
    </ScrollView>
  );
};

const styles = StyleSheet.create({
  image: {
    width: 200,
    height: 200,
    margin: 20,
  },
});
是否支持autolink RN框架版本
~8.8.0 Yes 0.82
~8.7.0 No 0.77
~8.6.4 Yes 0.72
<= 8.6.3-0.4.17@deprecated No 0.72

使用AutoLink的工程需要根据该文档配置,Autolink框架指导文档:https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink,并且工程已接入 Autolink,可跳过ManualLink配置。

ManualLink: 此步骤为手动配置原生依赖项的指导

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

2.1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK,需要在工程根目录的 oh-package.json5 添加 overrides 字段,指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号,也可以是一个模糊版本,还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
  }
}

2.2.引入原生端代码

目前有两种方法:

  1. 通过 har 包引入;
  2. 直接链接源码。

方法一:通过 har 包引入(推荐)

har 包位于三方库安装路径的 `harmony` 文件夹下。

打开 entry/oh-package.json5,添加以下依赖

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-fast-image": "file:../../node_modules/@react-native-ohos/react-native-fast-image/harmony/fast_image.har"
  }

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

方法二:直接链接源码

如需使用直接链接源码,请参考直接链接源码说明

2.3.配置 CMakeLists 和引入 FastImagePackage

若使用的是 <= 8.6.3-0.4.17 版本,请跳过本章。

打开 entry/src/main/cpp/CMakeLists.txt,添加:

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-fast-image/src/main/cpp" ./fast-image)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_fast_image)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp,添加:

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "FastImagePackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<RNOHGeneratedPackage>(ctx),
        std::make_shared<SamplePackage>(ctx),
+       std::make_shared<FastImagePackage>(ctx),
    };
}

2.4.在 ArkTs 侧引入 FastImagePackage

打开 entry/src/main/ets/RNPackagesFactory.ts,添加:

  ...
+ import {FastImagePackage} from '@react-native-ohos/react-native-fast-image/ts';

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

2.5. 运行

点击右上角的 sync 按钮

或者在终端执行:

cd entry
ohpm install

然后编译、运行即可。

3.约束与限制

3.1.兼容性

本文档内容基于以下版本验证通过:

  1. RNOH: 0.82.1; SDK: HarmonyOS API Version 21 Release SDK; IDE: DevEco Studio 6.0.1.260; ROM: 6.0.0.130;
  2. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  3. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
  4. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;

4.属性

"Platform"列表示该属性在原三方库上支持的平台。

"HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。

Name Description Type Required Platform HarmonyOS Support
source.uri 加载的远程图片资源. string yes All yes
source.headers? 加载图片时附带的请求头。例如:{Authorization: 'someAuthToken'}. object yes All yes
source.priority? 加载 url 优先级. enum no All no
source.cache? 设置缓存模式. enum no All no
defaultSource? 默认通过 require 加载的资源文件. (...). number yes All yes
resizeMode? 设置图片缩放模式. enum yes All yes
onLoadStart 图片开始加载时调用. function yes All yes
onProgress 图片正在加载时被调. 用. function yes All yes
onLoad 成功获取图片时调用. function yes All yes
onError 图片获取失败时调. 用. function yes All yes
onLoadEnd 图片加载完成时调用(无论加载成功还是失败). function yes All yes
tintColor? 设置图片的颜色,所有非透明像素的颜色更改为指定颜色. number | string yes All yes

5.静态方法

"Platform"列表示该属性在原三方库上支持的平台。

"HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性;no 则表示不支持;partially 表示部分支持。使用方法跨平台一致,效果对标 iOS 或 Android 的效果。

Name Description Type Required Platform HarmonyOS Support
FastImage.preload 预加载图片以便后续显示. function no All yes
FastImage.clearMemoryCache 从内存缓存中清除所有图片. function no All yes
FastImage.clearDiskCache 从磁盘缓存中清除所有图片. function no All yes

6.遗留问题

7.其他

8.开源协议

本项目基于 The MIT License (MIT) ,请自由地享受和参与开源。

Introduction

用户可用于在 React Native 应用中高效加载和管理图片,提升图片加载性能与用户体验。该项目支持多种图片加载事件监听、缩放模式设置及缓存管理,适配不同 RN 版本,提供便捷的安装与集成方式。【此简介由AI生成】

Customize your domain