更新记录

1.0.0（2026-06-29）

1、增加源码授权 2、增加图像导航

平台兼容性

uni-app(5.07)

uni-app x(5.07)

uts-imagePreview API 调用说明

导入

import { previewImage } from '@/uni_modules/uts-imagePreview'

调用

previewImage({
  urls: ['https://example.com/image.jpg'],
  current: 0,               // 默认显示第几张，从0开始
  maxZoom: 5,               // 最大缩放倍数
  tileSize: 1024,           // 切片尺寸（超大图模式）
  largeImageThreshold: 2048,// 超过此尺寸启用切片
  backgroundColor: '#000000',
  minimap: {                // 缩略图导航配置
    enable: true,
    position: 'topRight',
    size: 120,
    thumbnailUrl: 'https://example.com/thumb.jpg'
  },
  onClose: () => {},
  onChange: (index: number) => {}
})

MinimapOptions 缩略图导航配置

缩略图导航类似游戏小地图，缩放图片时在角落显示全图缩略图+当前视口框，支持拖动快速定位。

type MinimapPosition = 'topRight' | 'topLeft' | 'bottomRight' | 'bottomLeft' | 'topCenter' | 'bottomCenter' | 'leftCenter' | 'rightCenter'

type MinimapOptions = {
  enable?: boolean             // 是否启用，默认 true
  position?: MinimapPosition   // 位置关键词，默认 'topRight'
  x?: number                   // x 坐标(px)，设置后覆盖 position 水平方向
  y?: number                   // y 坐标(px)，设置后覆盖 position 垂直方向
  size?: number                // 尺寸(dp)，默认 120
  thumbnailUrl?: string        // 自定义缩略图地址，不传从原图自动生成
}

用法示例：

// 1. 默认右上角
previewImage({ urls: [...], minimap: { enable: true } })

// 2. 指定位置关键词
previewImage({ urls: [...], minimap: { position: 'bottomLeft' } })

// 3. 指定绝对坐标
previewImage({ urls: [...], minimap: { x: 20, y: 200 } })

// 4. 自定义缩略图
previewImage({ urls: [...], minimap: { thumbnailUrl: '/static/thumb.png' } })

// 5. 禁用缩略图导航
previewImage({ urls: [...], minimap: { enable: false } })

返回值

const viewer = previewImage({ urls: [...] })
viewer?.close()  // 主动关闭预览

返回 ImagePreviewResult 对象，包含 close() 方法。