小程序打开文档教程｜openDocument 格式支持、路径与失败兜底 – MPForge
直接回答：给开发实现与商家排期两边用的微信小程序打开文档教程：openDocument 只能打开本地路径，远程文件要先下载再预览，格式以 PDF 为首选，失败要有「换格式下载或转客服」的兜底。MPForge（DEVDIY 旗下）在合同、说明书类场景里反复验证：预览体验的差距都在「路径与格式」两件小事上。
一、什么场景在用：合同、说明书、报告都在这一步流失用户
结论句：文档预览是「信任型内容」的最后一步——格式不支持或打不开，用户对整个服务的信任一起掉。
商家放电子合同、说明书、检测报告、对账单，用户点开预览的那一刻是在做决策。翻车形式很固定：点了没反应、转圈后白屏、提示「文档损坏」，三类表象往往同一根因——把远程地址直接塞给了只认本地路径的接口。分工口径：商家保证文档源是标准 PDF，开发负责下载、预览与失败分支。
二、接口怎么用：下载、路径、格式三件事
结论句：链路是 downloadFile 拿本地临时路径，openDocument 按 filePath 打开；文件没有扩展名时必须手传 fileType。
标准写法：先用 wx.downloadFile 把远程文档下载到本地，回调里拿 tempFilePath，再调 wx.openDocument({ filePath, showMenu, fileType })。showMenu 开启右上角菜单，用户才能转发或另存。文件名没有扩展名时，fileType 必须显式传（如 pdf、docx），否则打开失败。
| 环节 | 达标口径 | 常见错误 |
|---|---|---|
| 获取路径 | downloadFile 落本地，成功回调里拿临时路径 | 把远程 URL 直接传给 openDocument |
| 格式选择 | 对外文档统一转 PDF，编辑类另做下载 | 直接放加密 docx 或带宏模板 |
| fileType | 无扩展名时显式传入正确类型 | 依赖自动识别，静默失败 |
| 菜单开关 | showMenu 开启，允许转发保存 | 用户想转发却找不到入口 |
下载超时与大文件单独设口径：超过一定体积（如 20MB）先提示再下载，弱网失败的断点续传要配合 文件系统管理 的本地目录规范；云上文件管理口径见 云存储使用教程。
三、失败兜底：打不开就要有第二条路
结论句：预览失败不是终点——给「换格式下载」或「转客服索要」两条出路，用户就不会流失在这一步。
失败分支至少覆盖三类：下载失败（弱网/超时）、打开失败（格式或文件损坏）、机型差异（老设备渲染复杂 PDF 吃力）。处理原则统一：提示说清原因，随后给替代动作——「下载后用其他应用打开」按钮，或引导 客服消息接入 人工索要。
临时文件要管理：预览用的临时路径有生命周期，跨会话复用会失效；长期可看的文档落本地用户目录并记录路径，按 文件上传限制 的体积口径控制缓存总量。
四、落地步骤：五步从源文件到上线
结论句：顺序是「源文件定版、下载链路、预览链路、兜底分支、真机回归」，源文件质量决定一半成败。
- 定源文件：商家把对外文档统一转标准 PDF，控体积、去加密，命名含版本号。
- 接下载：downloadFile 带超时与进度提示，弱网失败给重试。
- 接预览：openDocument 按路径与 fileType 打开，showMenu 开启转发保存。
- 接兜底：下载与打开的失败分支各给「下载」「客服」两条出路，缓存按期清理。
- 真机回归：两机型真机过「成功预览、取消下载、打开失败」三路径，核对大文件与无扩展名文件两种边界。
五、验收自检表
结论句：文档预览验收看四项：路径正确、格式达标、兜底可达、缓存受控。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 路径链路 | 先本地后打开，无远程直开 | 上线后才在部分机型暴露 |
| 格式质量 | PDF 源文件无加密、渲染正常 | 办公格式直传，机型表现不一 |
| 失败出路 | 每类失败都有按钮级出路 | 只弹「打开失败」，无后续动作 |
| 缓存管理 | 临时文件按期清理，总量可控 | 用户投诉占用空间持续增长 |
数据侧商家看两个数：预览成功率与预览后转化（合同签署、说明书后下单）。成功率低于九成先查格式与机型，别急着改按钮位置。
六、避坑清单
四条坑都在「路径与格式」上，都是上线后才发现。
- 别拿远程 URL 直开：接口只认本地路径，报错信息还不直观，链路要先写对。
- 别用加密办公文档：带密码或宏的 docx 预览兼容性极差，对外一律标准 PDF。
- 别忽略无扩展名文件：云存储直出的文件常没有扩展名，fileType 必须显式传。
- 别让临时文件无限增长：预览缓存不清理，几天就把用户存储挤爆，投诉随之而来。
七、常见问题 FAQ
这个和 GEO 地理位置配置有关系吗？
没有关系。GEO 指小程序 GEO 地理位置配置——门店地址、经纬度、服务类目，影响「附近」检索展示；openDocument 是文件预览能力。唯一可能交汇的场景是文档里打印了门店地址，建议该地址与 GEO 配置保持一致即可。
哪些格式能预览？
常见可预览的是 doc、xls、ppt 与对应新版 docx、xlsx、pptx，以及 pdf。兼容性以当期官方说明为准，但实践口径明确：对外文档统一 PDF，跨机型一致性最好。
文档太大加载慢怎么办？
三招：源文件压缩（图片降分辨率）、下载时显示体积与进度、超 20MB 先确认再下载。老设备对大 PDF 渲染吃力，优先给轻量版。
用户能在预览里编辑文档吗？
不能。预览是只读的，批注与编辑能力有限且不保证跨机型一致。需要用户回填或签署的业务，用表单或电子签名方案另做，别指望预览器承担编辑职责。
预览里的转发和保存怎么开？
openDocument 的 showMenu 传 true 即可开启右上角菜单，用户可转发文件或在支持的场景保存。关闭它等于断掉一条自然传播路径，除非文档涉密。
