支持双指缩放的图片查看组件

react-native-photo-view

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

项目介绍

@hxa-rn/react-native-photo-view 是 react-native-photo-view@1.5.3 的 HarmonyOS 适配包。它提供 Fabric 组件 PhotoView，用于加载远程或本地图片，并支持双指捏合缩放、双击缩放、图片平移、缩放类型和加载/手势事件。

鸿蒙端含 ArkTS Fabric 组件与 C++/ETS 自动链接产物。远程 http(s) 图片会先下载再解码渲染。

集成指南

npm install @hxa-rn/react-native-photo-view

包已声明 harmony.alias 为 react-native-photo-view。在 HarmonyOS 工程中配置 Metro / RNOH alias 后，业务代码仍从原包名导入：

import PhotoView from 'react-native-photo-view';

peerDependencies：react-native >= 0.72。

组件为 Fabric 原生组件，使用 RNOH 自动链接即可；不需要手动注册 TurboModule，也不需要手动链接 HAR。

使用说明

import React, {Component} from 'react';
import {StyleSheet, View} from 'react-native';
import PhotoView from 'react-native-photo-view';

export default class PhotoExample extends Component {
  _onScale = (event: {nativeEvent: unknown}) => {
    console.log('_onScale', event.nativeEvent);
  };
  _onTap = (event: {nativeEvent: unknown}) => {
    console.log('_onTap', event.nativeEvent);
  };
  _onViewTap = (event: {nativeEvent: unknown}) => {
    console.log('_onViewTap', event.nativeEvent);
  };
  _onLoadStart = (event: {nativeEvent: unknown}) => {
    console.log('_onLoadStart', event.nativeEvent);
  };
  _onLoad = (event: {nativeEvent: unknown}) => {
    console.log('_onLoad', event.nativeEvent);
  };
  _onLoadEnd = (event: {nativeEvent: unknown}) => {
    console.log('_onLoadEnd', event.nativeEvent);
  };

  render() {
    return (
      <View style={styles.container}>
        <PhotoView
          source={{uri: 'https://picsum.photos/id/237/800/600'}}
          onScale={this._onScale}
          onTap={this._onTap}
          onViewTap={this._onViewTap}
          onLoadStart={this._onLoadStart}
          onLoad={this._onLoad}
          onLoadEnd={this._onLoadEnd}
          showsVerticalScrollIndicator={true}
          showsHorizontalScrollIndicator={true}
          minimumZoomScale={0.5}
          maximumZoomScale={3}
          androidScaleType="center"
          style={styles.photo}
        />
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: '#F5FCFF',
  },
  photo: {
    width: 300,
    height: 300,
    justifyContent: 'center',
    alignItems: 'center',
    backgroundColor: 'black',
  },
});

本地资源可作为 source 传入，例如 source={require('./assets/photo.png')}。加载期间传入 loadingIndicatorSource 可显示占位图。

接口文档

以下为公开 Props / Events 签名摘要，不是可执行代码。

Props

属性	类型	说明
`source`	`{uri?: string, headers?: Record<string, string>} \| number`	远程 URL、本地 URI 或 `require` 资源
`loadingIndicatorSource`	`{uri?: string} \| number`	加载期间显示的占位图
`fadeDuration`	`number`	图片淡入时长，单位 ms
`minimumZoomScale` / `maximumZoomScale`	`number`	缩放边界，默认 `1` / `3`
`scale`	`number \| null`	程序化设置缩放比例
`androidScaleType`	`center`、`centerCrop`、`centerInside`、`fitCenter`、`fitStart`、`fitEnd`、`fitXY`、`matrix`	图片缩放显示方式
`androidZoomTransitionDuration`	`number`	双击缩放和回弹过渡时长，单位 ms
`showsHorizontalScrollIndicator` / `showsVerticalScrollIndicator`	`boolean`	iOS 专有。鸿蒙不支持（签名保留，空实现，不绘制系统滚动条）。详见不支持报告 U-01 / U-02

Events

事件	载荷
`onLoadStart` / `onLoadEnd`	`{}`
`onLoad`	`{width, height}`
`onError`	`{error}`
`onProgress`	`{loaded, total}`
`onTap`	`{x, y, scale}`
`onViewTap`	`{x, y}`
`onScale`	`{scale, scaleFactor, focusX, focusY}`

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

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

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/react-native-photo-view@1.5.6，不再使用本地 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。

约束与限制

项目	要求或限制
兼容性	HarmonyOS `compatibleSdkVersion` 为 `5.0.1(13)`；React Native `>=0.72`，使用 RNOH 新架构
权限	库模块自身无额外系统权限。宿主应用加载远程图片时需自行声明 `ohos.permission.INTERNET`
`matrix`	API 15+ 使用 `ImageFit.MATRIX`（原尺寸、左上对齐）；API 低于 15 时降级为 `center`
`fitStart` / `fitEnd`	使用 `Contain` 配合 Stack 顶对齐 / 底对齐近似实现
`onProgress`	远程 `http(s)` 自下载路径上报 `{loaded, total}`
点击坐标	鸿蒙端 `onTap` / `onViewTap` 返回组件相对比例坐标 `[0,1]`
滚动指示器	`showsHorizontalScrollIndicator` / `showsVerticalScrollIndicator` 鸿蒙不支持。二者依赖 iOS `UIScrollView` 系统滚动条；鸿蒙 PhotoView 以 `Stack` + `Image` + 变换实现缩放平移，不是可滚动容器，调用时空实现，界面不出现系统滚动条