uni.previewImage是最简最稳的跨端图片预览方案,能直接调起原生预览器,支持左右滑动、双指缩放和长按保存,但不支持自定义UI、水印或嵌入业务逻辑,需严格校验urls数组、current索引、临时路径及图片尺寸以避免各端异常。

uni.previewImage 是最简、最稳的方案,能直接跨端调起原生预览器,支持左右滑动、双指缩放(iOS/Android 原生 WebView 下默认启用)、长按保存,且无需手动管理 current 状态或监听页面滚动。
但如果你坚持用自定义组件(比如要加水印、定制 toolbar、或嵌入业务逻辑),就得绕开 swiper 做图片预览——它在多图大图场景下极易出问题。
为什么别用 swiper 做图片预览
不是不能用,是用了大概率踩坑:
-
swiper在 iOS 和小程序中对大图渲染内存占用高,滑动三五张后就卡顿甚至白屏 - 高度必须显式设置,否则
swiper-item内容塌陷——这不是 CSS 问题,是 nvue 和小程序原生组件的布局约束 -
autoplay和手势滑动冲突:用户刚拖一半,定时器触发跳转,体验断裂 - 嵌套
scroll-view实现缩放?iOS 真机上 touch 事件被吞,安卓缩放失灵,小程序直接禁用 -
previous-margin/next-margin在 App 端不生效,且和current同步错乱
用 uni.previewImage 时必须注意的 4 个参数细节
它看着简单,但传错一个字段,H5 就不滑动、小程序就只显示第一张、App 就闪退:
-
urls必须是字符串数组,哪怕只预览一张图也要写成['https://...'],传字符串会静默失败 -
current要传索引数字(如2)或字符串数字(如"2"),传undefined或非数字字符串会导致从第一张开始 - 临时路径(如
uni.chooseImage返回的tempFilePaths)必须全量传入urls,不能只传当前项——否则切换到其他图时路径失效 - H5 端若滑动卡顿,先检查图片宽是否 >2000px;服务端应返回适配预览尺寸的缩略图(建议最大宽 1200px)
需要缩放/长按保存/自定义 UI?得自己封装手势层
uni.previewImage 不开放内部 DOM 控制权,所有增强交互都得手写。核心是三个原生事件 + transform:
- 监听
touchstart/touchmove/touchend,别用@touch(Vue 修饰符会过滤掉部分touches) - 双指缩放靠
event.touches[0]和event.touches[1]的距离变化驱动scale,中心点必须是两指中点,否则放大偏移 - 单指拖拽前需判断
scale > 1,再算translateX/Y,否则会误触页面滚动 - 长按保存不能绑在
swiper上——它内部调了preventDefault();得在swiper-item内的view层绑定@longpress,并用uni.saveImageToPhotosAlbum
clientX 和小程序的 touches[0].clientX 值来源不同,差几个像素就会导致拖拽抖动。这个细节,90% 的开源组件都没处理。


















