接入文档预览

本文用于将您的业务系统中的 Office 文件（如 .docx、.xlsx、.pptx）嵌入网页预览。

预览功能必须依赖两个回调接口：
当前用户信息接口：{endpoint_url}/users/current/info
文件元信息接口：{endpoint_url}/files/{fileId}
用户打开预览时，石墨文档中台会调用这两个接口获取用户和文件信息。如果接口未实现或无法访问，文件将无法预览。

一、先按这 4 步完成接入

第 1 步：为文件准备一个唯一的 `fileId`

fileId 是您的系统中用于识别文件的 ID，由您自行生成和保存，例如：

my-preview-file-a1b2c3

同一个 fileId 应始终对应同一份文件内容。如果文件内容发生变化并且需要重新生成预览，请使用新的 fileId。

第 2 步：实现两个必需的回调接口

在您的后端实现以下接口，并确保部署后的石墨文档中台可以访问。

2.1 返回当前用户

返回示例：

{
  "id": "user-123",
  "name": "张三",
  "avatar": "https://example.com/avatar/user-123.png",
  "email": "zhangsan@example.com",
  "teamGuid": "team-123"
}

您的后端需要根据请求中的 token 识别当前用户，不要在接口中固定返回某一个用户。

2.2 返回要预览的文件

返回示例：

{
  "id": "my-preview-file-a1b2c3",
  "name": "示例文档.docx",
  "type": "file",
  "permissions": {
    "readable": true
  },
  "downloadUrl": "https://example.com/files/my-preview-file-a1b2c3/download",
  "ext": "docx"
}

预览文件时请特别注意：

type 必须为 file。

permissions.readable 必须为 true，否则用户无法查看。

downloadUrl 必须能被石墨文档中台访问，用于下载原文件。

ext 是不带点的文件扩展名，例如 docx、xlsx、pptx。

应根据当前用户返回真实权限，不要对所有用户固定返回 readable: true。

第 3 步：由后端生成 `signature` 和 `token`

用户打开预览页前，您的前端应先从自己的后端获取：

{
  "fileId": "my-preview-file-a1b2c3",
  "signature": "your-signature",
  "token": "your-user-token"
}

signature 用于证明请求来自您的应用，必须在后端使用 appId 和 appSecret 生成。

token 用于让您的回调接口识别当前用户，其格式和校验方式由您的系统决定。

不要将 appSecret 写入前端代码。

第 4 步：选择一种前端接入方式

两种方式的后端准备工作完全相同，都需要前面的 fileId、回调接口、signature 和 token。

方式一：自行组装 iframe 预览

适合只需快速展示预览页面场景。

预览地址格式：

https://{weboffice_host}/sdk/v2/api/cloud-files/{fileId}/page?signature={signature}&token={token}

将该地址设置为 iframe 的 src：

方式二：使用 `weboffice-js-sdk` 的 `connect`（推荐）

适合已经通过 weboffice-js-sdk 接入编辑，或希望由 SDK 统一创建 iframe、避免 query 携带鉴权场景。

安装 SDK：

页面中准备容器：

初始化预览：

必须设置 mode: 'preview'，否则 SDK 会按默认的编辑模式打开文件。
调用 connect() 后，SDK 会自动在 container 中创建预览 iframe。

二、完整预览流程

按照上面的步骤完成接入后，一次完整的文件预览会按下图执行。使用 connect() 时，weboffice-js-sdk 也会创建 iframe 打开预览页，因此两种接入方式不会改变下面的整体流程。

首次打开某些 Office 文件时可能需要等待转换。预览页会显示加载状态，并在处理完后展示文件。

三、预览加速（可选）

如果希望减少用户首次打开的等待时间，可以在用户打开页面前，由您的后端调用创建文件预览缓存接口。

这是优化项，不是完成基础预览接入的必需步骤。

预览结果会按 fileId 缓存。不要在保持原 fileId 不变的情况下，仅替换 downloadUrl 中的文件内容；如需预览新内容，请使用新的 fileId。

四、常见问题排查

页面提示无权限

检查以下内容：

token 是否属于当前用户，且尚未过期。

/users/current/info 是否能正确识别该用户。

/files/{fileId} 是否对该用户返回 permissions.readable: true。

页面一直加载或文件解析失败

检查以下内容：

downloadUrl 是否可从石墨文档中台所在网络访问。

downloadUrl 返回的是否为真实文件内容，而不是登录页、错误页或重定向失败页。

ext 是否与真实文件格式一致。

文件是否已损坏、加密或使用了当前不支持的格式。

iframe 中无法打开页面

检查您的页面 CSP、网关和反向代理配置，确保允许加载石墨文档中台域名的 iframe 及相关资源。

五、名词解释

接入方：将文档预览能力接入业务系统的客户团队，即您所在的团队。

石墨文档中台：负责鉴权、获取文件、转换文件和渲染预览页面的服务。

endpoint_url：您在石墨应用中配置的回调根地址，例如 https://api.example.com/shimo-callback。

weboffice_host：私有化部署的石墨文档中台访问域名，请使用实际环境地址。

回调接口：由您实现、供石墨文档中台调用的 HTTP 接口。文件和用户数据始终由您的系统管理。

预览文件：您的系统中已有的第三方文件，回调中 type 为 file，主要用于只读查看。

协作文件：由石墨文档套件承载的在线文档，可支持多人协同编辑。它与本文介绍的第三方文件预览不是同一种文件类型。

预览文档与协同文档的区别

协作文件是石墨在线文件类型（如 documentPro），支持多人实时协同编辑和预览访问。

预览文件是您的系统中已有的第三方文件（如 .docx、.xlsx、.pptx），仅支持预览，不支持编辑。

文件是预览文件还是协作文件，在生成 fileId 时就已确定，由您的系统负责维护对应关系。

两种文件使用相同的文件回调地址（/files/{fileId}），但返回字段不同。您的后端需要根据 fileId 判断文件类型，并返回对应的文件信息。

sdk-demo-go 可用于查看一套可运行的示例，但实际接入时只需按您的技术栈完成本文中的核心契约。

场景一：10 分钟创建预览文件

接入文档预览#

一、先按这 4 步完成接入#

第 1 步：为文件准备一个唯一的 fileId#

第 2 步：实现两个必需的回调接口#

2.1 返回当前用户#

2.2 返回要预览的文件#

第 3 步：由后端生成 signature 和 token#

第 4 步：选择一种前端接入方式#

方式一：自行组装 iframe 预览#

方式二：使用 weboffice-js-sdk 的 connect（推荐）#

二、完整预览流程#

三、预览加速（可选）#

四、常见问题排查#

页面提示无权限#

页面一直加载或文件解析失败#

iframe 中无法打开页面#

五、名词解释#

预览文档与协同文档的区别#