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

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

前置准备

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

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

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

一、名词释义

用户：使用你的平台的用户。

你的应用后端：你的应用后端服务，可以是 Java、Go、PHP、Python 实现，主要用提供你的平台前端业务需要的后端接口，同时也负责和石墨文档中台进行数据互通。

你的应用前端：你的应用前端代码，可以是 Web 或者 HTML5。

你的应用回调 URL 地址：石墨文档中台需要通过这个 URL 去请求你实现的回调接口，比如 https://your-endpoint-url.com

石墨文档中台：石墨文档中台服务

石墨文档中台域名：部署在你的机房的私有化版本石墨中台的访问域名，比如：https://weboffice-shimo-local.com

二、预览文档流程图

2.2. 步骤 2：准备好生成文件 id

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

2.3. 步骤 3：实现必要的回调接口供石墨文档中台调用

你的应用要实现以下两个接口供石墨文档中台服务端使用，接口必须使石墨文档中台服务端可访问。

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

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

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

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

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

2.4. 步骤 4：访问预览

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

预览地址格式为：

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

方式一（推荐）：手动创建预览的 HTML 页面

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

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

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

你可以修改这个 HTML，增加样式或者与后端互动的业务逻辑等。

方式二：使用石墨前端对接 demo

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

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

三、预览加速（可选）

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

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

一、名词释义#

二、预览文档流程图#

2.2. 步骤 2：准备好生成文件 id#

2.3. 步骤 3：实现必要的回调接口供石墨文档中台调用#

2.4. 步骤 4：访问预览#

方式一（推荐）：手动创建预览的 HTML 页面#

方式二：使用石墨前端对接 demo#

三、预览加速（可选）#