图片查看器组件，用于查看大图与图片详情

MultiLoaderImageViewer 鸿蒙 ArkTS 库

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

1. 项目介绍

本库将 ImageViewer 的图片查看器能力迁移为 HarmonyOS 原生 ArkTS HAR，包名 @hxa-atpc/multiloaderimageviewer，版本 1.0.2。支持多图左右翻页、双指捏合缩放、双击缩放、放大态拖拽平移与边界限制、页码指示器、占位图/失败图以及共享元素一镜到底转场。图片加载通过 ImageLoader 抽象由宿主注入，库内提供基于 ArkUI Image 的 DefaultImageLoader。

源码在 ohos_library/。ohos-hardemo 是手册 Demo，ohos-hardemo-auto 是黑盒用例 Demo。公开导出见 ohos_library/Index.ets。

2. 集成指南

下载

从 GitCode 克隆本仓库：

git clone https://gitcode.com/hxa-atpc/MultiLoaderImageViewer.git

安装并编译 Demo

在 ohos-hardemo/ 目录执行：

cd ohos-hardemo
ohpm install
hvigorw -e assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

HAP 产物：ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap。

集成到你的工程

对外集成请使用 方式一（ohpm 依赖已发布的 HAR）。方式二供克隆本仓库后修改 ohos_library 源码、本地联调使用。包名均为 @hxa-atpc/multiloaderimageviewer。

方式一：HAR 包依赖

工程根 oh-package.json5（保留已有 modelVersion 等字段，补充 dependencies）：

{
  "modelVersion": "6.0.2",
  "dependencies": {
    "@hxa-atpc/multiloaderimageviewer": "1.0.2"
  }
}

entry/oh-package.json5：

{
  "dependencies": {
    "@hxa-atpc/multiloaderimageviewer": "1.0.2"
  }
}

然后在工程根与 entry/ 分别执行：

ohpm install

方式二：源码依赖（开发 / 改库）

把宿主工程与本仓库的 ohos_library 放在相邻目录（或按实际相对路径改）。

常见目录关系（file: 路径均相对宿主工程根目录）：

场景	宿主工程位置	`ohos_library` 位置	工程根依赖示例
克隆全仓，宿主在仓库内	`MultiLoaderImageViewer/MyApp/`	`MultiLoaderImageViewer/ohos_library/`	`file:../ohos_library`
只拷贝 HAR 目录	`MyApp/`	与 `MyApp/` 同级 `ohos_library/`	`file:../ohos_library`
宿主在仓外	`workspace/MyApp/`	`workspace/MultiLoaderImageViewer/ohos_library/`	`file:../MultiLoaderImageViewer/ohos_library`

只改 oh-package.json5 不够，还必须改工程根 build-profile.json5：在 modules 里、entry 模块之后增加本库源码模块（name 以 ohos_library/src/main/module.json5 的 module.name 为准，常见为 library；srcPath 按上表相对路径填写），例如：

{
  "name": "library",
  "srcPath": "../ohos_library"
}

工程根 oh-package.json5（保留已有 modelVersion 等字段，补充 dependencies）：

{
  "modelVersion": "6.0.2",
  "dependencies": {
    "@hxa-atpc/multiloaderimageviewer": "file:../ohos_library"
  }
}

entry/oh-package.json5（相对 ohos_library 通常多一层 ../）：

{
  "dependencies": {
    "@hxa-atpc/multiloaderimageviewer": "file:../../ohos_library"
  }
}

工程根 build-profile.json5（在已有 app 段上补充 modules；compatibleSdkVersion 与 useNormalizedOHMUrl 不可省略）：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.1.1(19)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        }
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    },
    {
      "name": "library",
      "srcPath": "../ohos_library"
    }
  ]
}

然后在工程根与 entry/ 分别执行：

ohpm install

导入包名：@hxa-atpc/multiloaderimageviewer。

3. 使用说明

import { ImageViewer, DefaultImageLoader, sharedElementId } from '@hxa-atpc/multiloaderimageviewer';
import { window } from '@kit.ArkUI';

ImageViewer.setGlobalDefaultImageLoader(new DefaultImageLoader());

ImageViewer.load($r('app.media.gif'))
  .start(this.getUIContext(), this.pathStack);

ImageViewer.load(listData)
  .selection(position)
  .showIndicator(true)
  .placeholder($r('app.media.ic_image_placeholder'))
  .error($r('app.media.ic_image_error'))
  .orientation(window.Orientation.PORTRAIT)
  .start(this.getUIContext(), this.pathStack);

共享元素一镜到底：宿主缩略图绑定 .geometryTransition(sharedElementId(index))，且源页必须在 NavDestination 内。未设置本次 imageLoader 且未设置全局默认加载器时，start() 抛出 Error。

手册 Demo 见 ohos-hardemo，黑盒 Demo 见 ohos-hardemo-auto。

运行 Demo

cd ohos-hardemo
ohpm install
hvigorw -e assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

HAP 产物：ohos-hardemo/entry/build/default/outputs/default/entry-default-unsigned.hap。

4. 接口文档

下列均为 Index.ets 公开导出。签名以源码为准。

入口

接口	说明
`ImageViewer`	`load` / `setGlobalDefaultImageLoader` / `selection` / `placeholder` / `error` / `imageLoader` / `showIndicator` / `indicator` / `orientation` / `theme` / `activityOptionsCompat` / `imageViewerClass` / `extras` / `start`
`SHARED_ELEMENT`	共享元素 id 前缀（`'shared_element'`）
`sharedElementId(index)`	列表/单图共享元素 id（`${SHARED_ELEMENT}_${index}`）
`IMAGE_VIEWER_SHARED_ELEMENT`	`SHARED_ELEMENT` 别名
`IMAGE_VIEWER_PAGE_NAME`	路由名 `'image_viewer_page'`
`DEFAULT_MIN_SCALE` / `DEFAULT_MID_SCALE` / `DEFAULT_MAX_SCALE`	缩放档 1.0 / 1.75 / 3.0

类型与加载器

接口	说明
`ImageViewerModel` / `ImageViewerPlaceholder` / `ImageViewerSource`	数据、占位、源类型
`ImageDataSource`	`getDataSource()`
`ImageLoader`	`loadImage(model, placeholder?, error?): ImageLoadResult`
`DefaultImageLoader`	基于 ArkUI Image 的默认加载器
`ImageLoadResult`	加载结果

会话与页面

接口	说明
`ImageViewerSpec`	进程级单例：`position` / `listData` / `showIndicator` / `placeholderDrawable` / `errorDrawable` / `themeConfig` / `orientation` / `imageLoader()` / `hasGlobalDefaultImageLoader()` / `extras` / `reset()`
`ImageViewerPageParams`	查看页参数
`imageViewerBuilder` / `ImageViewerRoot`	查看页构建器与根组件
`ImageViewerThemeConfig` / `ImageViewerTransitionOptions`	主题与转场

适配器与手势

接口	说明
`ImageViewerAdapter`	多图适配器
`OnItemClickListener`	条目点击
`ImageViewerItemView`	单页视图
`PhotoViewModel`	缩放/平移状态

5. 约束与限制

兼容性

项	版本
上游 Atpc SDK	ImageViewer `1.2.0`（jenly1314/ImageViewer）
鸿蒙适配版本	`1.0.2`
版本号对照	`1.2.0-ohos-1.0.2`
鸿蒙 SDK	`compatibleSdkVersion` / `targetSdkVersion`：`5.1.1(19) / 6.1.1(24)`

权限

兼容性

鸿蒙 SDK：compatibleSdkVersion 5.1.0(18)，targetSdkVersion 5.1.0(18)
上游 ATPC / Android SDK：ImageViewer 1.2.0

权限

ohos.permission.INTERNET：仅加载网络图片时由宿主声明；HAR 本身不声明网络权限

其它

ImageViewerSpec 为进程级单例，同一时刻仅支持一个查看会话
宿主必须挂载 Navigation + NavPathStack 并合并 routerMap
HAR 模块名为 library

6. 开源license

7. 问题反馈渠道

使用过程中如有问题，欢迎在仓库提交 Issue，我们会及时跟进：

GitCode Issue：https://gitcode.com/hxa-atpc/MultiLoaderImageViewer/issues
也欢迎提交 Pull Request 共建：https://gitcode.com/hxa-atpc/MultiLoaderImageViewer/pulls

提交 Issue 时请尽量附上 HarmonyOS SDK 版本、复现步骤与 hilog 日志。

ohpm install @hxa-atpc/multiloaderimageviewer

Introduction