最稳妥方案是App端用uni.openDocument预览Word/Excel,H5端必须走微软Office Web Viewer;App需先下载再转换路径,H5需确保URL公网可访问且正确编码。

直接用 uni.openDocument 在 App 端预览 Word/Excel 是最稳妥的方案;H5 端则必须走微软 Office Web Viewer,否则浏览器会强制下载。
App端:uni.openDocument 要先下载再打开,路径转换不能少
Android 和 iOS 都不支持直接传网络 URL 给 uni.openDocument,必须先调用 uni.downloadFile 下载到临时路径,再用 plus.io.convertLocalFileSystemURL 转成本地可读路径。
-
uni.downloadFile返回的tempFilePath是临时地址,iOS 可直接传给uni.openDocument(部分版本),但 Android 必须用plus.io.convertLocalFileSystemURL转换,否则报错“file not found” -
fileType参数建议显式传入,比如'docx'或'xlsx',不传可能在某些 Android 设备上 fallback 失败 - 下载失败时
statusCode不一定是 404,也可能是 0(网络中断)或 -1(权限拒绝),需统一判断!downloadRes.tempFilePath - Android 10+ 需在
AndroidManifest.xml加android:requestLegacyExternalStorage="true",否则convertLocalFileSystemURL返回空路径
H5端:Office Web Viewer 要求 URL 公网可访问且编码正确
浏览器没原生 Office 渲染能力,只能靠微软的 https://view.officeapps.live.com/op/view.aspx 中转。它不接受内网地址、localhost、带登录态的 redirect URL,也不处理未编码的中文或空格。
- URL 必须是 HTTPS 且公网可直连,比如
https://cdn.example.com/report.xlsx,不能是后端接口如/api/file?id=123 - 必须用
encodeURIComponent包裹原始 URL,否则src=https://xxx/合同.docx会被截断为src=https://xxx/ - 文件大小建议 ≤10MB,超大 Excel 表格加载慢或白屏,无错误提示,只能靠超时兜底
- PDF 也能走这个链路,但注意:微软对 PDF 的渲染效果不如原生 PDF.js 精准,页眉页脚、水印可能丢失
iOS 和 Android 对 doc/docx/xls/xlsx 的支持差异很实际
不是所有设备都能打开 .doc 或 .xls——iOS 自带预览只支持 .docx/.xlsx,Android 则依赖是否装了 WPS 或 Office,没装就直接失败,且不弹提示。
- 后端尽量统一转成 .docx/.xlsx 格式再下发,避免前端做格式兼容判断
- iOS 上
uni.openDocument打开后,用户点左上角“完成”才能回你的 App;Android 上部分机型返回键直接退出预览页,需监听plus.webview.currentWebview().addEventListener('backbutton')做拦截 - 不要假设
fail回调一定触发:WPS 未安装时,Android 可能静默失败,界面卡住,建议加 3 秒超时setTimeout主动提示“请安装 WPS”
真正麻烦的不是代码行数,而是路径转换时机、URL 编码边界、以及没装阅读器时的静默失败——这些点不提前埋监控,上线后用户只会说“点不开”,根本不会告诉你错在哪。


















