ImagePreview 图片预览

介绍

以服务调用的方式全屏预览图片，支持手势缩放、滑动切换、页码显示、长按回调等功能。

引入

import { TnImagePreview, TnImagePreviewOption } from "@tuniao/tn-ui";

代码演示

基础用法

调用 TnImagePreview.show() 并传入图片 URL 数组即可展示图片预览，支持左右滑动切换、双击缩放、双指缩放。

点我查看代码

import { TnImagePreview } from "@tuniao/tn-ui";

@Entry
@ComponentV2
struct ImagePreviewBasic {
  private images: string[] = [
    "https://picsum.photos/id/10/800/600",
    "https://picsum.photos/id/20/800/600",
    "https://picsum.photos/id/30/800/600",
    "https://picsum.photos/id/40/800/600",
    "https://picsum.photos/id/50/800/600"
  ];

  build() {
    Column() {
      Button("预览图片")
        .onClick(() => {
          TnImagePreview.show(
            this.images
          );
        });
    }
  }
}

指定初始图片

通过 TnImagePreviewOption 的 startIndex 属性指定预览时的初始图片索引。

点我查看代码

import { TnImagePreview, TnImagePreviewOption } from "@tuniao/tn-ui";

// 从第3张开始预览
const option = new TnImagePreviewOption();
option.startIndex = 2;
TnImagePreview.show(
  this.images,
  option
);

页码位置

通过 indexPosition 属性设置页码指示器的位置，支持 "top" 和 "bottom"。

点我查看代码

// 页码显示在顶部
const option = new TnImagePreviewOption();
option.indexPosition = "top";
TnImagePreview.show(
  this.images,
  option
);

隐藏页码

通过 showIndex 设置为 false 隐藏页码指示器。

点我查看代码

const option = new TnImagePreviewOption();
option.showIndex = false;
TnImagePreview.show(
  this.images,
  option
);

关闭循环滑动

通过 loop 设置为 false 禁用循环滑动，到达末尾后无法继续滑动。

点我查看代码

const option = new TnImagePreviewOption();
option.loop = false;
TnImagePreview.show(
  this.images,
  option
);

点击图片不关闭

通过 closeOnClickImage 设置为 false，点击图片后不关闭预览（需点击遮罩区域关闭）。

点我查看代码

const option = new TnImagePreviewOption();
option.closeOnClickImage = false;
TnImagePreview.show(
  this.images,
  option
);

自定义缩放比例

通过 maxScale 和 minScale 属性设置图片的最大和最小缩放倍数。

点我查看代码

const option = new TnImagePreviewOption();
option.maxScale = 5;
TnImagePreview.show(
  this.images,
  option
);

监听点击和长按事件

通过 onImageClick 和 onImageLongPress 监听图片的点击和长按事件。建议配合 closeOnClickImage = false 使用，避免点击后直接关闭预览。

点我查看代码

const option = new TnImagePreviewOption();
option.closeOnClickImage = false;
option.onImageClick = (index: number): void => {
  console.info(`点击了第 ${index} 张图片`);
};
option.onImageLongPress = (index: number): void => {
  console.info(`长按了第 ${index} 张图片`);
};
TnImagePreview.show(
  this.images,
  option
);

API

TnImagePreview.show

TnImagePreview.show(urls: ResourceStr[], option?: TnImagePreviewOption): void

参数	说明	类型	必填
urls	图片地址数组	ResourceStr[]	是
option	预览配置选项	TnImagePreviewOption	否

TnImagePreview.hide

TnImagePreview.hide(): void

手动关闭当前图片预览。

TnImagePreviewOption

参数	说明	类型	默认值
startIndex	初始显示图片索引	number	0
swipeDuration	切换动画时长（ms）	number	200
showIndex	是否显示页码	boolean	true
indexPosition	页码位置	"top" | "bottom"	"bottom"
loop	是否循环切换	boolean	true
closeOnClickImage	点击图片是否关闭	boolean	true
closeOnClickOverlay	点击遮罩层是否关闭	boolean	true
maxScale	最大缩放倍数	number	3
minScale	最小缩放倍数	number	1

Events（通过 TnImagePreviewOption 设置）

事件名	说明	回调参数
onImageClick	点击图片时触发	(index: number) => void
onImageLongPress	长按图片时触发	(index: number) => void