41 行
3.4 KiB
Markdown
41 行
3.4 KiB
Markdown
# 企业微信自建应用原生文件预览调研
|
||
|
||
## 结论
|
||
|
||
企业微信自建应用内可以预览 PDF，不应以普通链接在 WebView 中的下载表现判断企业微信是否具备 PDF 预览能力。官方 JS-SDK 提供 `ww.previewFile` / `wx.previewFile`，兼容企业微信 iOS、Android，由企业微信原生层下载 URL 对应文件并在内置预览器中打开，官方说明支持图片、音频、视频、文档等格式。
|
||
|
||
本任务应优先验证并接入企业微信原生 `previewFile`，而不是先引入 PDF.js 或服务端转图片。PC 普通浏览器继续使用浏览器预览；两端保持“查看原件”业务能力一致，但底层实现按运行环境分流。
|
||
|
||
## 官方证据
|
||
|
||
- 企业微信开发者中心《预览文件》：<https://developer.work.weixin.qq.com/document/path/100623>
|
||
- 参数为 `url`、`size`、`name`。
|
||
- `size` 必填且必须准确，否则打开失败。
|
||
- `name` 应包含正确文件扩展名。
|
||
- 原生层会重新请求文件 URL；iOS WKWebView 中的 Cookie 不会自动带给原生请求。
|
||
- 官方建议资源 cookie-free；需要鉴权时，在 URL 中携带业务侧短时 access token。
|
||
- 腾讯企业微信维护的 JS-SDK：<https://github.com/TencentWecom/wecom-jssdk>
|
||
- npm 包 `@wecom/jssdk` 的类型定义明确标注 `previewFile` 兼容 WeCom iOS、Android。
|
||
- SDK 将 `previewFile` 调用传递给企业微信原生 `WeixinJSBridge`。
|
||
- JS-SDK 总入口：<https://developer.work.weixin.qq.com/document/path/90547>
|
||
- 自建应用需完成 JS-SDK 注册和当前页面 URL 的 `config` 签名；官方 SDK README 说明自建应用只需提供 `getConfigSignature`。
|
||
|
||
## 对 hyb-oa 的影响
|
||
|
||
1. 当前项目没有 JS-SDK ticket/signature 接口，也未引入 `@wecom/jssdk`，需要补最小自建应用签名链路。
|
||
2. 发票已有短时签名文件 URL，可复用其 cookie-free 形态，但报销详情还需返回准确 `fileSize` 和带扩展名的 `originalName`。
|
||
3. 报销附件当前仅支持带 OA Bearer token 的 Blob 下载；企业微信原生请求不会携带该请求头，需要增加对象级授权后的短时签名 URL，不能改为公开文件。
|
||
4. 签名 URL 必须短时、限定文件与申请人、保留实际打开审计；不得把长期 token、Cookie、Secret 或原始企微凭据放入 URL。
|
||
5. 移动企微内调用 `previewFile`；普通 PC 浏览器使用签名 URL 的浏览器预览。非企微移动浏览器可保留明确下载或浏览器预览 fallback。
|
||
|
||
## 建议验证顺序
|
||
|
||
1. 先用不含业务数据的安全 PDF，在生产同域受控页面完成 JS-SDK `config + previewFile` 技术探针，验证马建勇实际 Android/iOS 企业微信版本。
|
||
2. 探针通过后再接发票短时 URL和附件短时 URL，避免拿真实票据做首轮 SDK 调试。
|
||
3. 合成数据覆盖：签名 URL 权限、过期/篡改拒绝、准确 size/name、企微原生调用、PC fallback、审批人只读边界。
|
||
4. 生产部署后先用安全 PDF 验收，再让经理查看真实报销材料；材料可见前不得审批。
|
||
|
||
## 行业实现归纳
|
||
|
||
企业微信 H5 的常见稳妥实现是“JS-SDK 原生预览 + cookie-free 短时签名 URL + Web fallback”。其关键不在 PDF 渲染库，而在把受保护文件临时转换成原生层可拉取、可过期、可审计的 URL。PDF.js 或服务端转图片适合作为官方原生接口在特定机型失败后的第二级 fallback，不应作为本项目首选路径。
|