uni.previewImage 是 uni-app 原生大图预览方案，需传数字索引而非 URL 作 current，urls 必为数组；小程序不支持临时路径，需网络地址或 base64；长按保存须用 longPressActions 而非 @longpress；保存图片需先 download 再 save；H5 不支持保存；indicator、loop 等配置可优化体验。
uni.previewImage 是 uni-app 唯一原生支持的大图全屏预览方案，不需要自己写 canvas 缩放、手势逻辑，也不用引入第三方组件。它直接调起系统级预览器，性能稳定、跨端一致（App、微信小程序、H5 均可用），但必须注意几个关键点，否则会白屏、报错或保存失败。
uni.previewImage 的 current 参数必须是索引，不是 URL
很多人传 current: 'https://xxx.jpg'，结果预览打开后显示空白或首张图——这是最常见错误。在 urls 是数组的前提下，current 必须是数字索引（从 0 开始），不能是字符串 URL。
正确写法：
uni.previewImage({
current: index, // ✅ 数字，比如点击第 2 张图就传 1
urls: this.imgList // ['a.jpg', 'b.jpg', 'c.jpg']
})
错误写法：
uni.previewImage({
current: 'https://xxx.jpg', // ❌ H5 可能勉强工作，App 和小程序大概率失效
urls: this.imgList
})
- 如果只预览单张图，
urls仍要传数组：urls: [singleUrl]，current: 0 - 微信小程序不支持本地临时路径（如
tempFilePath）直接传入urls，必须是网络地址或 base64（base64 需加前缀data:image/png;base64,） - App 端支持本地路径（
_www/xxx.png或file://协议），但 H5 不支持
长按保存必须用 longPressActions，不能靠 @longpress 绑定
在 <image> 标签上写 @longpress="saveImg" 在微信小程序里完全无效——小程序禁止对 <image> 直接绑定长按事件。唯一可靠方式是通过 uni.previewImage 的 longPressActions 配置项触发。
关键细节：
-
longPressActions仅在 App 和微信小程序生效，H5 不支持长按菜单 -
itemList最多支持 3 项，超出会被截断；文字建议用简体中文，避免 emoji 或特殊符号导致 iOS 崩溃 -
success回调里的res.tapIndex是点击菜单的序号，res.index是当前预览图在urls中的真实索引（注意：不是传入的current！因为用户可能已滑动） - 保存前务必校验
res.index是否有效，防止越界取this.imgList[res.index]
uni.saveImageToPhotosAlbum 要处理 filePath 来源和权限拒绝
uni.saveImageToPhotosAlbum 的 filePath 不能直接传网络 URL（微信小程序会报错 fail errCode: -1），必须先用 uni.downloadFile 下载到本地临时路径，再传给保存 API。
典型流程：
const res = await uni.downloadFile({ url: imgUrl })
if (res.statusCode === 200) {
uni.saveImageToPhotosAlbum({ filePath: res.tempFilePath })
}
- App 端可直传网络 URL（部分安卓机型例外），但为了一致性，建议所有平台都走 download → save 流程
- 首次调用时，iOS 和 Android 都会弹权限框；若用户点“不允许”，
fail的err.errMsg会含auth deny，此时应引导用户去设置页手动开启 - H5 端不支持保存到相册，
uni.saveImageToPhotosAlbum会静默失败，需提前判断uni.getSystemInfoSync().platform !== 'h5'
indicator、loop 等配置影响体验但常被忽略
默认预览器只显示点状指示器，且单图时仍允许左右滑动（造成误操作）。加上几行配置就能显著提升可用性：
-
indicator: 'number'：显示 “2/5” 这样的数字提示，比点更直观 -
loop: this.imgList.length > 1：仅当图片数 ≥ 2 时开启循环，单图禁用避免无意义滑动 -
showmenu: false（App 端）：关闭原生右上角菜单，避免和自定义longPressActions冲突 - 微信小程序不支持
showmenu，也不支持自定义顶部按钮，所以别在这儿浪费时间
真正容易出问题的是缩放行为：预览器默认支持双指缩放，但缩放后长按菜单可能无法触发（尤其 iOS），这不是 bug，是系统限制——缩放态下长按优先触发系统菜单。如果业务强依赖长按保存，建议文档里注明“请先双击恢复原图再长按”。
