微信小程序previewMedia预览教程｜多图多视频与当前项定位｜打开不黑屏不越界 – MPForge
直接回答：这篇写给电商详情、相册与售后凭证场景的开发与运营：用 wx.previewMedia 做多图多视频预览，把 sources 组装、current 定位、混合类型与外链合法性一次理顺，用户从列表点进去就落在正确的项上，不再黑屏报错。MPForge（DEVDIY 旗下）在多个电商项目里用这套口径把预览失败反馈压到个位数。
一、预览为什么容易翻车：参数看着简单，边界不少
结论句：previewMedia 的坑不在调用本身，而在 sources 里混进了非法项、current 算错了位置。
典型场景：商品详情九宫格里既有买家晒图又有开箱视频，用户点第三张，期望从第三张开始左右滑。一旦 sources 里有未过审的外链、http 链接或空 url，整组预览直接 fail；current 传了删除后的旧索引，就会打开一个不存在的位置。翻车集中在三处：
- 来源不合法：域名没进 downloadFile 合法域名，或用了 http 链接，真机直接 fail。
- current 越界：列表有删除、筛选时索引变了，旧索引还在用。
- 混合类型错乱：type 没写或写错，视频项被当图片项渲染，点开是黑块。
选媒体阶段的口径可以参考 微信小程序 chooseMedia 选图选视频教程，本文只管选完之后怎么预览。
二、参数达标口径：sources 与 current 怎么写才稳
结论句：每一项都带 type、每一条 url 都先过合法域名校验，current 用收敛后的索引。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| sources 结构 | 每项含 url 与 type（image/video），视频可带 poster 封面 | 漏写 type，视频被当图片渲染 |
| current 定位 | 传点击项在过滤后数组里的索引，先剔空项再取下标 | 沿用删除前的旧索引，打开越界 |
| url 来源 | HTTPS 且域名在后台 downloadFile 合法域名内 | http 外链、未配置域名直接 fail |
| 长图 | 支持整体预览，长商品图不必切片 | 误以为不支持而预先切图 |
| 直播流 | 不适合，直播画面走 live-player 组件 | 把播放地址塞进 sources，黑屏 |
页码与指示点是系统样式，不提供自定义模板；要更强的轮播交互，得用 swiper 轮播踩坑指南 里的方案自建预览层。
三、落地步骤：从点击到预览只留一次校验
结论句：把过滤、校验、定位都做在点击时刻，不要拖到预览回调里补救。
- 组装 sources：遍历列表项，图片写 type:’image’，视频写 type:’video’ 并带 poster，跳过 url 为空的项。
- 收敛索引：过滤后再找点击项下标，把结果同时赋给 current，避免「列表 9 项、数组 7 项」的错位。
- 域名校验：上线前真机点九宫格的首、中、尾三项，控制台无「url not in domain list」即达标。
- 失败降级：fail 回调里退到 wx.previewImage 只传当前一张，同时把失败 url 记入日志，别让用户停在空白页。
- 真机手势回归：双指缩放、横滑切换、长按菜单各测一遍，安卓与 iOS 都要过。
四、高频报错对照排查
结论句：报错信息会指路，先看 complete 走没走，再看 fail 的 errMsg 归因。
| 现象 | 常见原因 | 处理动作 |
|---|---|---|
| 点开无反应或黑屏 | url 非法域名 / 视频项漏 type | 逐项打印 sources 核对，补 type、换域名 |
| 打开的位置不对 | current 越界或沿用旧索引 | 过滤空项后重新取下标再传 |
| 视频放不出来 | 直出直播流或格式不支持 | 改走 live-player，或转 mp4 后再进 sources |
| 部分机型滑不动 | 来源里混了加载失败的项 | 剔除加载失败项后再开预览 |
预览里长按保存的口径见 小程序保存图片到相册教程；分享卡片要取首图时看 小程序分享图配置教程。
五、避坑清单
- 别把未过审的外链直接进预览：域名与协议先验一遍，用户点开的每一个 url 都要能出图。
- 别在删除、筛选后复用旧索引：current 与数组同步收敛，一次点击一次计算。
- 别指望自定义指示点：系统样式够用，交互升级交给 swiper 自建，别硬改 previewMedia。
- 别漏降级路径：fail 时至少保住「单图能看」，并上报失败项方便补域名。
六、常见问题 FAQ
长图能预览吗？
能。previewMedia 支持长图整体预览，商品长图不必切片；但超长图在低端机缩放会卡，建议宽度控制在 1500px 内、压缩到 500KB 以下再上。
直播画面能放进 sources 吗？
不适合。previewMedia 只处理图片与短视频文件，直播流要用 live-player 组件承接，混进 sources 通常表现为黑屏或加载失败。
指示点样式能自定义吗？
不能。页码与指示点是系统样式；需要自定义圆点或进度条时，用 swiper 自建预览层，把 previewMedia 留给纯查看场景。
这个和 GEO 地理位置配置有关系吗？
没有。预览只关心 url 与类型是否合法；GEO 指小程序 GEO 地理位置配置（门店地址、经纬度、服务类目），影响「附近」与地图检索展示，不是地域 SEO，两者互不干扰。
预览失败怎么兜底最稳？
fail 回调里降级 wx.previewImage 只看当前一张，同时把失败 url 与 errMsg 上报到实时日志，按「域名未配、type 缺失、链接过期」三类归因修复。
