wx.previewImage能预览单张图片吗？

Question

**问题：wx.previewImage 能预览单张图片吗？** 在微信小程序开发中，`wx.previewImage` 通常用于预览图片列表。有开发者疑问：当只有一张图片时，能否使用 `wx.previewImage` 进行预览？实际测试表明，即使 `urls` 数组中仅包含一个图片链接，该接口仍可正常调用并显示图片。但需注意，`current` 参数必须与 `urls` 中的某一项匹配，否则预览可能无法正确加载。因此，`wx.previewImage` 支持单张图片预览，只需确保传入格式正确。

Answer 1

1. 基础概念：wx.previewImage 是什么？

wx.previewImage 是微信小程序提供的一个原生 API，用于在全屏模式下预览一张或多张图片。开发者可以通过该接口实现用户点击缩略图后查看高清大图的功能。

其基本调用方式如下：

wx.previewImage({
  current: 'https://example.com/image1.jpg',
  urls: ['https://example.com/image1.jpg']
});

其中，urls 是图片 URL 的数组，而 current 指定当前要显示的图片链接，必须是 urls 中的一项。

2. 核心问题解析：能否预览单张图片？

许多开发者误以为 wx.previewImage 只适用于多图场景，但实际上它完全支持单张图片预览。

关键在于参数的正确配置：

• urls：即使只有一张图片，也必须传入数组形式，如 ['url']。
• current：必须与 urls 数组中的某个值完全匹配（包括大小写和协议头）。

若 current 不在 urls 中，微信客户端将无法定位目标图片，导致预览失败或白屏。

3. 实际案例演示

以下是一个常见的错误用法与正确用法对比：

场景	代码示例	结果
错误：current 不在 urls 中	{ current: 'http://a.jpg', urls: ['https://a.jpg'] }	可能无法加载
正确：协议一致且匹配	{ current: 'https://a.jpg', urls: ['https://a.jpg'] }	成功预览
正确：单图数组	{ current: imgList[0], urls: imgList }	正常显示

4. 技术深度剖析：底层机制与注意事项

从运行时角度看，微信客户端在调用 wx.previewImage 时会启动内置的图片查看器组件，该组件并不关心 urls 长度，仅依赖索引映射。

当 urls 数组长度为 1 时，查看器仍会初始化分页控制器，但由于只有一项，左右滑动无效（UI 上表现为禁用状态）。

需要注意的细节包括：

1. URL 必须为 HTTPS 或合法域名，受小程序 request 合法域名校验限制。
2. Base64 图片不支持预览（部分安卓机型例外，但官方不推荐）。
3. 本地临时路径（如相机拍照返回的 tempFilePaths）可直接使用。
4. 网络图片建议提前加载或缓存，避免预览时卡顿。
5. 在某些低版本微信客户端中，若图片过大可能导致内存溢出。

5. 流程图：调用逻辑判断流程

graph TD
    A[触发预览事件] --> B{图片数量}
    B -->|单张| C[构造单元素urls数组]
    B -->|多张| D[构造完整urls数组]
    C --> E[设置current为该图片URL]
    D --> F[设置current为目标图片URL]
    E --> G[调用wx.previewImage]
    F --> G
    G --> H{是否报错?}
    H -->|是| I[检查URL协议、域名、拼写]
    H -->|否| J[成功预览]

6. 最佳实践建议

对于有 5 年以上经验的开发者，应关注性能优化与用户体验层面的设计：

• 统一图片 CDN 协议，避免 HTTP/HTTPS 混用导致 current 匹配失败。
• 封装通用预览函数，自动处理单图/多图场景：

function previewImage(current, urls) {
  const imageList = Array.isArray(urls) ? urls : [urls];
  // 确保 current 存在于列表中
  if (!imageList.includes(current)) {
    console.warn('current image not in urls list');
    return;
  }
  wx.previewImage({ current, urls: imageList });
}

此封装提升了健壮性，适用于复杂业务场景如动态图文混排、富文本渲染等。