# ohos_image_view_zoom

**Repository Path**: openharmony-sig/ohos_image_view_zoom

## Basic Information

- **Project Name**: ohos_image_view_zoom
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 35
- **Created**: 2022-04-16
- **Last Updated**: 2025-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ImageViewZoom

## 简介

> ImageViewZoom 支持加载 Resource 或 PixelMap 图片，支持设置图像显示类型功能，支持缩放功能，支持平移功能，双击放大功能，可以监听图片大小，资源变化事件，支持清除显示图片功能。

## 效果展示

![avatar](screenshot/效果展示.gif)

## 下载安装

```shell
ohpm install @ohos/imageviewzoom 
```

OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitee.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md)

## 使用说明

ets 代码依赖

```
import {ImageViewTouchDate, ImageViewTouch, DisplayType} from "@ohos/imageviewzoom"
import {PixelMapUtils} from "./PixelMapUtils"
...
//创建model对象
@State private model: ImageViewTouch.Model = new ImageViewTouch.Model();
...
//使用ImageViewTouch组件
ImageViewTouch({ model: $model });
...
```

在Swiper组件内使用，如果有图片放大后切图的场景，需要在Swiper组件的onAnimationEnd方法内调用gestureConversion方法，调整手势方向，以避免图片index未变化时，出现手势竞争问题，如下所示：
```
 if (this.currentIndex == index && this.data[this.currentIndex].getScale() > 1) {
   this.data[this.currentIndex].gestureConversion(PanDirection.All, SwipeDirection.None)
 }
```

## 接口说明

1. 设置图片资源

   `public setImageSrc(src ?: Resource | PixelMap | string | null, matrix ?: object | null, minZoom ?: number, maxZoom ?: number): void` 
    `setImageSrc接口新增src参数的string类型`

2. 设置默认图像显示类型

   `public setDisplayType(type: DisplayType)`
   `public getDisplayType(): DisplayType`

   DisplayType.NONE：图像默认不缩放。
   DisplayType.FIT_TO_SCREEN：图像将始终使用此视图的边界呈现。
   DisplayType.FIT_IF_BIGGER：仅当大于此视图的边界时才会缩放图像。
   DisplayType.FIT_HEIGHT：图像将被缩放以适合设备的高度。
   DisplayType.FIT_WIDTH：图像将被缩放以适合设备的宽度。

3. 清除当前显示的图片

   `public dispose(): void`

4. 设置是否能够双击

   `public setDoubleTapEnabled(value: boolean): void`

5. 设置是否能够缩放

   `public setScaleEnabled(value: boolean): void`

6. 设置是否能够滚动

   `public setScrollEnabled(value: boolean): void`

7. 设置图片资源变化监听事件

   `public setOnDrawableChangedListener(listener: OnDrawableChangeListener): void`

8. 设置图片大小变化监听事件

   `public setOnLayoutChangeListener(listener: OnLayoutChangeListener): void`

9. 恢复显示

   `public resetDisplay(): void`

10. 恢复视图矩阵
   
   `public resetMatrix(): void`

11. 获取当前允许的最大图像比例
   
   `public getMaxScale(): number`

12. 获取当前允许的最小图像比例
   
   `public getMinScale(): number`

13. 设置当前视图矩阵
   
   `public setImageMatrix(matrix: object): void`

14. 返回当前视图矩阵
   
   `public getImageViewMatrix(): object`

15. 打印矩阵详细信息
   
   `public printMatrix(matrix: object): void`

16. 返回当前视图比例

   `public getScale(): number`

17. 缩放到目标比例

   `public zoomTo(scale: number, durationMs: number): void`

18. 设置是否能够双击
   
   `public setDoubleTapEnabled(value: boolean): void`

19. 设置是否能够缩放

   `public setScaleEnabled(value: boolean): void`

20. 返回是否能够双击状态值
   
   `public getDoubleTapEnabled(): boolean`

21. 判断图片能否根据手势滚动

   `public canScroll(): boolean`

22. 设置双击监听事件

   `public setDoubleTapListener(listener: OnImageViewTouchDoubleTapListener): void`

23. 设置单击监听事件

   `public setSingleTapListener(listener: OnImageViewTouchSingleTapListener): void`

24. 设置滑动手势与拖拽手势的方向

   `public gestureConversion(panDirection: PanDirection, swipeDirection?: SwipeDirection, vertical?: boolean)`

    `gestureConversion接口是用于处理拖拽手势PanGesture和滑动手势SwipeGesture的手势竞争问题，通过动态的设置两个手势的触发方向，解决手势竞争。`

25. 图片资源变化监听

   `onDrawableChanged(src: Resource | PixelMap | string): void`
   `onDrawableChanged方法新增src参数的string类型`


## 约束与限制

在下述版本验证通过：
- DevEco Studio: NEXT Beta1-5.0.3.806,SDK:API12 Release(5.0.0.66)
- DevEco Studio NEXT Developer Beta3: 5.0(5.0.3.530), SDK: API12 (5.0.0.35(SP3))

## 目录结构

```
|---- ImageViewZoom
|     |---- entry  # 示例代码文件夹
|     |---- library  # ImageViewZoom库文件夹
|        |----src
|           |----main
|              |----ets
|                 |---- components
|                       |---- utils  # 工具库
|                             |---- IDisposable.ets  # 提供清除图片接口
|                       |---- ImageViewTouch.ets  # 自定义控件
|           |---- index.ets  # 对外接口
|     |---- README.MD  # 安装使用方法
|     |---- README_zh.MD  # 安装使用方法
|     |---- LICENSE #证书
```

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitee.com/openharmony-sig/ohos_ftp_srv/issues) 给组件，当然，也非常欢迎发 [PR](https://gitee.com/openharmony-sig/ohos_ftp_srv/pulls)共建 。

## 开源协议

本项目基于 [MIT license](https://gitee.com/openharmony-sig/ImageViewZoom/blob/master/LICENSE) ，请自由地享受和参与开源。