10分钟创建预览文档

通过本文档可快速预览一个 Office 文档（如 Word、Excel、PPT）。
接入方需要启动一个 HTTP 服务端，并提供文中指定的回调接口供石墨文档中台调用。关于回调接口的解释，参考：【后端】回调接口说明。

前置准备

接入方必须实现两个回调接口：

用户预览时石墨 SDK 会自动回调这两个接口：先调用当前用户信息接口进行鉴权，再调用文档元信息接口获取文件下载地址等信息。如果这两个接口未正确实现，预览将无法正常工作。

预览文档与协同文档的区别：
【协同文档】是石墨在线文档类型（如 documentPro），支持多人实时协同编辑和预览访问。
【预览文档】是第三方文件类型（如 .docx、.xlsx、.pptx），仅支持预览访问，不支持编辑。
一个文件是预览还是协同类型，在生成 fileId 时就已确定，由接入方维护。
两种文档的回调接口地址相同（/files/{fileId}），但返回的字段不同，接入方需根据 fileId 判断并返回对应类型的数据。

预览文档流程图

步骤 1：接入方生成文件 id

例如：my-preview-file-a1b2c3
这个 id 完全由接入方决定是什么，建议使用 uuid 等方式避免重复。

步骤 2：接入方提供回调接口

接入方要实现以下两个接口供石墨服务端使用，接口必须使石墨服务端可访问。

文档元信息接口
提供一个石墨服务端可访问的 HTTP 接口，GET 请求：
http://your-endpoint-url.com/files/my-preview-file-a1b2c3 时，结果为：

{
  "id": "my-preview-file-a1b2c3",
  "name": "示例文档.docx",
  "type": "file",
  "permissions": {
    "readable": true
  },
  "downloadUrl": "http://your-endpoint-url.com/download/my-preview-file-a1b2c3.docx",
  "ext": "docx"
}

注意与协同文档回调的区别：
type 固定为 file，表示第三方文件类型。
必须提供 downloadUrl，石墨服务器会通过此地址下载文件内容进行解析渲染。
必须提供 ext 字段（不带 .），用于标识文件扩展名，例如 docx、xlsx、pptx。
permissions 中至少需要 readable: true，预览模式只关注可读权限。

当前用户信息接口
提供一个石墨服务端可访问的 HTTP 接口，GET 请求
http://your-endpoint-url.com/users/current/info 时，结果为：

{
  "id": "userid123",
  "name": "张三",
  "avatar": "http://fake.site/user-123.png",
  "email": "user123@fake.site",
  "teamGuid": "123"
}

步骤 3：访问预览

预览文档无需像协同文档那样先调用创建文件接口，直接通过 iframe 访问预览页面即可。

预览地址格式为：

https://office.shimoapi.com/sdk/v2/api/cloud-files/{fileId}/page?signature={signature}&token={token}

使用石墨前端对接 demo（推荐）

前端 demo 地址：https://github.com/shimo-open/sdk-demo-fe
下载项目，在 index.js 中填入 signature, token, endpointUrl, fileId 这四个变量后，用浏览器打开 index.html 即可看到预览页面。

手动创建

写一个最简单的 html 页面，将预览页面嵌入 iframe 中。

新建一个 index.html 文件，内容如下：

用浏览器打开 index.html 文件，页面中将出现文档的预览内容。

首次访问预览时，石墨后台会异步创建预览缓存，此过程可能需要等待。缓存创建完成后，预览页面会自动刷新显示完整内容。

预览加速（可选）

如果需要加快用户首次打开文件的速度，可在服务端提前调用创建文件预览缓存接口创建预览缓存，这样用户打开预览时无需等待。

注意：由于预览缓存机制，同一 fileId 经过第一次预览产生预览缓存后，再更新回调中 downloadUrl 的内容是无法修改预览结果的。如需更新预览内容，需要使用新的 fileId。

预览文档流程图#

步骤 1：接入方生成文件 id#

步骤 2：接入方提供回调接口#

步骤 3：访问预览#

使用石墨前端对接 demo（推荐）#

手动创建#