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 + 变换实现缩放平移，不是可滚动容器，调用时空实现，界面不出现系统滚动条

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

欢迎在 AtomGit 提交 Issue。也可以通过 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-photo-view

https://gitcode.com/hxa-rn/react-native-photo-view/issues