文章目录
-
- 一、预览区放在业务页面里
- 二、创建应用
- 三、前端嵌入预览
- 四、用真实文档核对
- 五、官方文档
业务系统的 OA、合同或附件列表里，用户点击一份文档后，浏览器底部出现下载。文件落到本地，再用 WPS 客户端打开。没有客户端的电脑、临时工位和手机都看不了这份文档，体验非常割裂，反复下载文件也会非常占用用户内存 😭
常见实现是把附件名直接链到 .docx 地址，或接口用 Content-Disposition: attachment 返回文件。浏览器会把它当成下载任务，不会在当前页渲染。用户本意只是想预览和编辑文档，并没有选文档「另存为」，只是业务系统把文档预览做成了下载。
本文面向要把文档预览嵌进业务系统的接入方。读完可以做到：同一份附件在业务页面中打开，即时渲染，所见即所得，不触发下载，也不要求安装客户端 ✨
做法是：附件列表的点击打开业务侧预览页，并带上该文件在业务中的 ID，例如 /preview?fileId=合同附件记录 ID。文字文档都进这个页，不要对文件存储地址使用 window.open。
左边是现在常见的路径，右边是嵌进页面之后的路径。
一、预览区放在业务页面里
接入方需提前在业务页面中预留好用于渲染预览的区域容器。用户点击附件列表中的 .docx 后，文档会在该区域内直接打开：地址栏仍保持业务域名，浏览器底部也不会出现下载栏。。
下表对比现在和做成之后：
| 点附件 | 浏览器开始下载 | 当前页或预览页打开 |
| 看内容 | 需安装 WPS 客户端 | 在浏览器中查看 |
| 文件位置 | 本机下载目录增加一份副本 | 文件仍在业务存储中 |
本文使用 WPS 开放平台的 WebOffice。前端通过 Web SDK 在页面中嵌入 iframe。文件来源和访问权限由接入方服务端回调提供。
开始前准备：开放平台账号、一份带标题和表格的真实 .docx。本教程将带大家完成以下三件事：创建应用、把预览嵌进页面、用真实文档验证。
二、创建应用
注意： AppSecret 只放在服务端，不要写进页面代码。
从下载版本获取最新 JSSDK （v1.1.20 及以上），不要用过旧的 umd 包对接当前文档。
三、前端嵌入预览
将 web-office-sdk-solution.umd.js 放到页面可引用的路径（官方包文件名）。文字文档使用 OfficeType.Writer。fileId 是业务系统中的文件 ID。WebOffice 用这个 ID 向回调服务请求文件。
给挂载节点设置明确宽高（受 iframe 限制，容器没有具体宽高时，文档可能无法渲染）
以下是实现代码示例（可参考前端快速开始，落地前记得将 APP_ID、FILE_ID 换成实际值）：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover"
/>
<title>附件预览</title>
<style>
html,
body {
margin: 0;
height: 100%;
}
#office {
width: 100%;
height: 100%;
}
</style>
</head>
<script src="./web-office-sdk-solution.umd.js"></script>
<body>
<div id="office"></div>
<script>
window.onload = function () {
var instance = WebOfficeSDK.init({
officeType: WebOfficeSDK.OfficeType.Writer,
appId: "APP_ID",
fileId: "FILE_ID",
mount: document.querySelector("#office"),
});
instance.on("fileOpen", function (data) {
if (data && data.success) {
console.log("预览打开了");
}
});
};
</script>
</body>
</html>
APP_ID 是开发者后台的应用 ID。FILE_ID 是业务系统里这份文档的文件 ID，不是公网文件链接。
init 会在 #office 中插入 iframe。
说明： fileOpen 在打开成功或失败时都会触发。参数里 success 为 true 时，控制台出现「预览打开了」。失败或页面空白时，到开发者后台进行日志排查。常见原因是回调未接通，或 officeType 与文件类型不一致。
说明： 若预览区在标签页或侧栏里，初始化时节点为 display:none 或高度为 0，打开后也会空白。先让 #office 在可见区域占满一屏，验证通过后再调整布局。手机用微信打开时，页面 viewport 可参考官方移动端来写，否则 iframe 里会图标过小、双击放大。
表格使用 OfficeType.Spreadsheet，演示文稿使用 Presentation。类型填错可能导致打开失败或乱码。附件列表同时有文字文档和表格时，按后缀选择 officeType，不要固定为 Writer。
四、用真实文档核对
流程跑通后，可用业务里的真实合同、通知（至少包含标题、表格和页眉）进行生产环境下的核对检验。从附件进入预览页后核对： 1. 浏览器未开始下载 2. 正文和表格在页面中可见 3. 未要求安装 WPS 客户端 PC端用 Chrome 80 以上的浏览器核对完这三项后，可再用微信打开同一份附件，验证移动端也能同时适配。
主路径到这里就通了：列表点击附件 → 预览页携带 fileId → SDK init → 页面中显示文档。过程中不应再次触发下载。
接入 OA 还要配服务端回调：回调网关须公网可访问，文件下载地址和预览权限在回调中返回。可参考官方 Web SDK 概述 和服务端回调，先把本地 Demo 跑通。
五、官方文档
- WPS 开放平台
- 快速开始（建应用、试用）
- 开发者后台
- Web SDK 概述
- 前端快速开始（init 参数）
