react-native-photo-view

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

项目介绍

@hxa-rn/react-native-photo-view 是 [email protected] 的 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 br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 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