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

v1.0.0

Published

a day ago

react-native-image-zoom for HarmonyOS

0High
0Medium
0Low

react-native harmony harmonyos

react-native-image-zoom

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

项目介绍

本项目是 react-native-image-zoom 的 React Native for OpenHarmony 适配包，提供高性能的可缩放图片组件 ImageZoom 与通用内容缩放容器 Zoomable。缩放、平移及点击手势由 react-native-gesture-handler 与 react-native-reanimated 驱动，本库为纯 JavaScript/TypeScript 实现，不包含本库自身的原生模块。

主要能力包括：

ImageZoom：基于 Animated.Image 实现的可缩放图片组件，支持远程/本地图片与双击、捏合、平移等手势。
Zoomable：基于 Animated.View 实现的通用内容缩放容器，可包裹任意 React 节点。
支持 Ref 方法 reset、zoom、getInfo，用于控制缩放与获取布局信息。
导出 ZOOM_TYPE、ANIMATION_VALUE 枚举及相关类型定义。

集成指南

安装

在 React Native 工程根目录执行：

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

本库要求宿主工程提供以下 peer dependency：

react-native >=0.72
react >=16.x.x
@react-native-ohos/[email protected]
@react-native-ohos/react-native-reanimated@~3.6.5
[email protected]

Autolinking

本库为纯 JavaScript 实现，自身不包含原生模块，无需在 oh-package.json5 中手动声明依赖或执行额外的链接操作。RNOH 工程按 package.json 的 harmony.alias 字段完成模块解析，安装后直接导入即可。

导入

import {
  ImageZoom,
  Zoomable,
  ZOOM_TYPE,
  ANIMATION_VALUE,
  type ImageZoomProps,
  type ImageZoomRef,
  type ZoomableProps,
  type ZoomableRef,
} from '@hxa-rn/react-native-image-zoom';

入口实际导出 ImageZoom、Zoomable 两个组件，以及 ZOOM_TYPE、ANIMATION_VALUE 枚举和相关类型。

使用说明

基础用法

import { ImageZoom } from '@hxa-rn/react-native-image-zoom';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export function ImagePreview() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <ImageZoom
        uri="https://picsum.photos/800/600"
        style={{ width: '100%', height: 320 }}
        minScale={1}
        maxScale={5}
        isDoubleTapEnabled
        doubleTapScale={3}
        onInteractionStart={() => console.log('开始交互')}
        onInteractionEnd={() => console.log('结束交互')}
      />
    </GestureHandlerRootView>
  );
}

GestureHandlerRootView 应作为使用缩放组件区域的根容器，确保手势被正确接收。ImageZoom 默认使用 resizeMode="contain"，可通过 ImageProps 同名属性覆盖。若要使用本地图片或更完整的图片源配置，传入 source，其优先级高于 uri：

<ImageZoom
  source={require('./assets/photo.png')}
  style={{ width: '100%', height: 320 }}
/>

isDoubleTapEnabled 与 isSingleTapEnabled 默认关闭，需要显式开启后对应的手势与回调才会生效。

使用 Zoomable

import { Text, View } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Zoomable } from '@hxa-rn/react-native-image-zoom';

export function ZoomableContent() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Zoomable style={{ flex: 1 }} minScale={1} maxScale={4} isDoubleTapEnabled>
        <View style={{ padding: 20, backgroundColor: '#e3f2fd' }}>
          <Text>可缩放的任意内容</Text>
        </View>
      </Zoomable>
    </GestureHandlerRootView>
  );
}

Zoomable 基于 Animated.View 实现，可包裹任意 React 节点；除图片相关属性外，其缩放与手势属性与 ImageZoom 相同。ImageZoom 与 Zoomable 均支持 Ref（ImageZoomRef / ZoomableRef，两者为同一接口），可通过 reset()、zoom()、getInfo() 控制缩放与获取信息，详见接口文档。

接口文档

以下 API 依据 src/index.ts、src/types.ts 及相关类型定义整理。

ImageZoom

基于 Animated.Image 实现的可缩放图片组件，支持 ImageProps（除 source 外）及缩放属性；source 的优先级高于 uri，默认 resizeMode 为 contain。

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | uri | string | '' | 远程或本地图片 URI；source 存在时由 source 覆盖。 | | source | ImageSourcePropType | 未声明 | React Native 图片源，如 require(...) 或 URI 对象。 | | 其余图片属性 | ImageProps（不含 source） | — | 例如 style、resizeMode、onLoad，会透传至 Animated.Image。 |

Zoomable

基于 Animated.View 实现的通用内容缩放容器，可包裹任意 React 节点；除图片相关属性外，其缩放与手势属性与 ImageZoom 相同，并接受 ViewProps 及 Reanimated 动画属性，透传至内部 Animated.View。

共享缩放属性（ZoomProps）

ImageZoom 与 Zoomable 均支持以下缩放与手势属性：

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | minScale | number | 1 | 捏合缩放可达到的最小比例。 | | maxScale | number | 5 | 捏合缩放可达到的最大比例。 | | scale | SharedValue<number> | useSharedValue(1) | 外部传入的 Reanimated 共享缩放值；组件会随交互更新其值。 | | doubleTapScale | number | 3 | 双击放大时使用的缩放比例。 | | maxPanPointers | number | 2 | 双指平移手势允许的最大触点数。 | | isPanEnabled | boolean | true | 是否启用平移手势。 | | isPinchEnabled | boolean | true | 是否启用捏合缩放。 | | isSingleTapEnabled | boolean | false | 是否启用单击手势。 | | isDoubleTapEnabled | boolean | false | 是否启用双击手势。启用后，双击可在放大和重置之间切换，手势结束时会将内容约束在可见范围内。 | | onInteractionStart | () => void | — | 一次交互开始时触发。 | | onInteractionEnd | () => void | — | 捏合、平移等交互全部结束时触发。 | | onPinchStart | (event) => void | — | 捏合开始时触发。 | | onPinchEnd | (event, success: boolean) => void | — | 捏合结束时触发，success 表示手势是否正常结束。 | | onPanStart | (event) => void | — | 平移开始时触发。 | | onPanEnd | (event, success: boolean) => void | — | 平移结束时触发，success 表示手势是否正常结束。 | | onSingleTap | (event) => void | — | 单击识别成功时触发。 | | onDoubleTap | (zoomType: ZOOM_TYPE) => void | — | 双击缩放时触发，参数为 ZOOM_IN 或 ZOOM_OUT。 | | onProgrammaticZoom | (zoomType: ZOOM_TYPE) => void | — | 调用 Ref 的 zoom 时触发；比例大于 1 为 ZOOM_IN，否则为 ZOOM_OUT。 | | onResetAnimationEnd | (finished?: boolean, values?) => void | — | 重置动画结束时触发。finished 表示动画是否完整结束，values 给出 SCALE、焦点和位移动画状态。 |

Ref 方法

ImageZoom 与 Zoomable 均支持 Ref，类型分别为 ImageZoomRef 与 ZoomableRef（两者为同一接口）。zoom 的 x 与 y 是组件容器坐标。

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | reset() | — | void | 以动画方式将缩放比例、焦点和位移恢复为初始状态。 | | zoom({ scale, x, y }) | { scale: number; x: number; y: number } | void | 以动画方式缩放到指定比例及容器内坐标；当 scale <= 1 时执行重置。 | | getInfo() | — | GetInfoCallback 的返回值 | 返回当前容器尺寸、缩放后尺寸、可见区域及变换值。 |

getInfo() 的返回值结构：

{
  container: { width: number; height: number; center: { x: number; y: number } };
  scaledSize: { width: number; height: number };
  visibleArea: { x: number; y: number; width: number; height: number };
  transformations: { translateX: number; translateY: number; scale: number };
}

回调相关枚举

enum ZOOM_TYPE {
  ZOOM_IN = 'ZOOM_IN',
  ZOOM_OUT = 'ZOOM_OUT',
}

enum ANIMATION_VALUE {
  SCALE = 'SCALE',
  FOCAL_X = 'FOCAL_X',
  FOCAL_Y = 'FOCAL_Y',
  TRANSLATE_X = 'TRANSLATE_X',
  TRANSLATE_Y = 'TRANSLATE_Y',
}

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | | :-- | --- | | Node.js | >=20 | | React Native for OpenHarmony | 0.72.139 | | HarmonyOS SDK | 6.0.1(21) 及以上 |

运行步骤

在仓库根目录安装依赖并构建产物：
```
npm install
```
生成供 example 工程安装的本地安装包：
```
npm pack
```
该命令会在仓库根目录生成 hxa-rn-react-native-image-zoom-1.0.0.tgz，example 工程通过 file: 方式引用该文件。
进入 example 目录安装依赖：
```
cd example
npm install
```
生成 HarmonyOS 侧使用的 React Native JavaScript Bundle：
```
npm run dev
```
使用 DevEco Studio 打开 example/harmony，同步依赖并完成签名配置后，构建并运行应用。

约束与限制

兼容性

| 依赖 | 要求 | | --- | --- | | React Native for OpenHarmony | 以宿主工程配置为准；示例工程使用 0.72.139 | | HarmonyOS SDK | 以宿主工程配置为准 | | Example 工程 compatibleSdkVersion | 6.0.1(21) | | Example 工程 targetSdkVersion | 6.1.1(24) | | Node.js | >=18（示例工程要求 >=20） |

使用限制

本库为纯 JavaScript 实现，自身不包含原生模块；所有缩放能力依赖 react-native-gesture-handler 和 react-native-reanimated，缺少任一依赖时组件无法正常处理手势与动画。
GestureHandlerRootView 应作为使用缩放组件区域的根容器，确保手势被正确接收。
ImageZoom 使用 resizeMode="contain" 作为默认图片适配方式；可通过 ImageProps 的同名属性覆盖。
isDoubleTapEnabled 与 isSingleTapEnabled 默认为 false，未开启时对应的双击、单击手势不会响应。
本库仅导出 ImageZoom、Zoomable 两个组件及相关类型与枚举，src/hooks、src/utils 下的实现属于内部细节，不作为公开 API。

系统权限

本库为纯 JavaScript 实现，不包含原生模块，未声明任何 HarmonyOS 系统权限。示例工程 example 也未声明 requestPermissions；若宿主应用需要加载网络图片，需自行在 module.json5 中声明 ohos.permission.INTERNET。

开源 License

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

问题反馈渠道

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

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