更新记录

1.0.3（2026-08-17）

窗口级原生图片浏览器，支持流畅缩放、横向分页、缩略图联动、安全区顶部栏、加载动画和索引回调。

平台兼容性

uni-app(4.71)

uni-app x(4.33)

fsyang-image-preview

Android / iOS 窗口级原生图片浏览器。插件直接覆盖当前应用窗口，不打开新页面、Activity 或 WebView。

功能

• 主图按屏幕宽度 100% 等比显示并垂直居中
• 原生横向分页、双指缩放、双击缩放和放大后拖动
• 顶部自动避开 Android 状态栏及 iOS 安全区
• 底部可横向滚动的缩略图列表，与主图双向联动
• 白色加载动画、黑色经典背景
• 主图变化、关闭和错误回调

使用

import {
  openImagePreview,
  closeImagePreview,
  onImagePreviewChange,
  onImagePreviewClose,
  onImagePreviewError
} from '@/uni_modules/fsyang-image-preview'

// 建议在 App.vue onLaunch 中注册一次。
onImagePreviewChange((event) => {
  console.log('当前图片', event.index, event.url, event.total)
})

onImagePreviewClose((event) => {
  console.log('预览关闭', event.index, event.reason)
})

onImagePreviewError((event) => {
  console.error('图片预览失败', event.code, event.message)
})

openImagePreview({
  images: [
    'https://example.com/1.jpg',
    'https://example.com/2.jpg'
  ],
  current: 0,
  maxZoom: 4,
  showThumbnails: true,
  closeOnTap: false,
  backgroundColor: '#000000'
})

// 业务需要时主动关闭。
closeImagePreview()

参数

回调

onImagePreviewChange 在首次展示和主图落到新下标时触发。点击缩略图跳转也会触发。

平台要求

• Android 5.0（API 21）及以上
• iOS 15.0 及以上
• 需要自定义基座或云打包，标准基座不包含本地新增的 UTS 原生插件