uni-app 中实现九宫格图片预览的实战指南
uni.previewImage 可直接实现九宫格图片预览，但需确保 urls 为完整 URL 数组，current 为 urls 中存在的字符串；九宫格用 flex + aspect-ratio + mode="aspectFill" 布局，点击时传对应 src 而非索引。
核心工具：用 uni.previewImage 实现大图预览
想要实现类似微信朋友圈那种点击放大、滑动浏览的体验？其实不必大费周章去写复杂的 Canvas 或手势逻辑。uni-app 内置的 uni.previewImage API 已经封装好了这些功能。不过，用起来顺手与否，关键全在于传参格式和图片数组的构造。
这里有个必须牢记的前提：urls 参数要求数组里的每一项，都必须是完整可访问的图片地址。这意味着网络图片需要包含协议头（如 https://），而本地图片路径则因平台而异。例如，H5 端仅支持网络图片；小程序和 App 端虽然支持 uni.chooseImage 返回的临时路径，但一旦页面发生跳转，这些临时文件就可能失效，导致预览失败。
一个典型的“坑”是设置 current 参数。它必须是一个字符串，并且要与 urls 数组中的某一项完全一致——包括大小写和路径分隔符。曾遇到过在 iOS 小程序上，仅仅因为文件扩展名的大小写不同（.jpg 与 .JPG），就被系统判定为两张不同的图片，从而无法正确定位。
- 数组准备：确保
urls是一个长度至少为1的字符串数组，每一项都是有效的图片地址。 - 当前图定位：
current的值必须是urls数组中真实存在的某个地址字符串，不能传入数组索引。 - 平台差异：H5 端只认网络图片；App 和小程序支持本地临时路径，但需注意其生命周期。
- 数据校验：如果图片源来自用户选择，建议在调用预览前，先用
Array.map或filter对数组做一次清理，剔除空值或无效项。
构建流畅的九宫格布局
预览功能搞定了，但九宫格本身布局不好，体验照样大打折扣。常见问题是什么？图片变形、重叠，或者在宽屏设备上挤成一团。
核心思路是利用 Flex 布局的灵活性。但要注意，直接给图片设置固定的宽高是下策，因为图片比例各异。更优雅的做法是控制容器的宽高比。这里推荐使用 aspect-ratio 属性配合 object-fit: cover（对应 uni-app 中 image 标签的 mode="aspectFill"），让图片在固定区域内等比例裁剪填充，再结合 flex-wrap: wrap 实现自动换行。
几个容易翻车的细节：忘记给 image 标签设置 mode="aspectFill"，导致图片被拉伸；或者容器没有设置最大宽度限制，在平板上单行显示了所有图片，变得极其狭窄。
- 外层容器：使用
view包裹每张图片，设置flex: 1并限制max-width: 33.33%（实现三列布局），辅以少许内边距如padding: 4px作为间隔。 - 图片样式：为
image标签添加mode="aspectFill"，并设置样式width: 100%; height: 100%;使其填满容器。 - 父级设置：父容器应用
display: flex; flex-wrap: wrap; justify-content: flex-start;。 - 性能优化：为提升首屏体验，可给
image添加lazy-load属性（注意该特性在 H5 端不生效）。H5 端可考虑监听图片加载事件，在加载完成前显示占位图。
精准定位：点击哪张就预览哪张
布局好了，点击事件也得跟上。这里的关键在于，传递给 uni.previewImage 的 current 参数，必须是图片地址本身，而不是它在数组中的索引。
所以，正确的流程是：在点击事件中，根据索引 index 从图片地址数组 urls 里取出对应的地址字符串，再将这个字符串作为 current 传入。听起来简单，但边界情况不容忽视：比如数组为空、索引越界，或者取出的地址是空字符串。这些情况会导致 uni.previewImage 静默失败，控制台可能没有任何错误提示。
- 事件绑定：在模板中绑定点击事件，例如
@click="handlePreview(index)"。 - 方法实现：在处理方法中，先进行有效性校验：
if (!urls[index]) return。然后调用：uni.previewImage({ current: urls[i], urls: urls }); - 重复地址处理：如果数组中存在完全相同的 URL，
current会定位到第一个匹配的项，这可能导致用户感知的预览顺序与点击顺序不一致。 - 交互反馈限制：目前
uni.previewImage不提供页面切换的回调接口，因此无法在预览时高亮显示当前页码或实现程序化跳转，只能依赖用户手动滑动。
平台疑难杂症排查
功能都实现了，但在不同平台上可能遇到一些“特色”问题。例如，安卓 App 上点击后黑屏，或者 iOS 上图片预览时显得模糊。
安卓的黑屏问题，很多时候源于图片路径协议不完整（比如用了“//”开头的相对协议）或网络策略限制。而 iOS 上的模糊，则常常是因为原图分辨率不足，被 aspectFill 模式拉伸放大后导致的。真机调试时，打开开发者工具的 Network 面板，查看图片请求是否成功（状态码 200），是首要的排查步骤。
- 安卓 App 黑屏：检查项目配置，确认是否允许明文 HTTP 请求（涉及
android:usesCleartextTraffic配置）。如果图片是 HTTP 链接，而 App 强制使用 HTTPS，则会导致加载失败。 - iOS 图片模糊：确保使用的图片素材本身有足够的分辨率（建议宽度至少 750px 以上）。另外，尽量避免将超长的 base64 字符串直接作为图片地址传入，在某些 iOS 版本上可能解析异常。
- 通用样式陷阱：避免对图片或其父容器使用
transform: scale()或zoom这类会改变元素几何属性的 CSS，它们可能会干扰图片的正常渲染。 - 体验优化：由于首次调用
uni.previewImage可能需要初始化原生模块，会有短暂延迟。在调用前添加一个简单的 loading 提示，可以显著改善用户体验。
最复杂的场景，莫过于图片源混杂——页面里同时存在网络图、本地临时文件、用户相册中的文件路径。面对这种情况，一个治本的建议是：在上传环节就做统一。先将所有图片通过 uni.uploadFile 上传至服务器，获得统一的网络 URL 后再进行预览和展示，这远比在客户端硬扛多端路径兼容性要稳健得多。
