10 分钟创建协同文档

通过本文档可快速创建一个 word 文档，并在石墨编辑器中使用。
接入方需要启动一个 HTTP 服务端，并提供文中指定的回调接口供石墨文档中台调用。关于回调接口的解释，参考：【后端】回调接口说明。

前置准备

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

当前用户信息接口

文档元信息接口

当用户通过前端 SDK 访问协同文档时，石墨 SDK 会自动回调这两个接口：先调用当前用户信息接口进行鉴权，再调用文档元信息接口获取文件类型和权限等信息。如果这两个接口未正确实现，协同文档将无法正常加载。

协同文档流程图

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

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

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

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

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

{
  "id": "my-new-file-u98213",
  "name": "第一个协同文档",
  "type": "documentPro",
  "permissions": {
    "commentable": true,
    "editable": true,
    "readable": true,
    "copyable": true,
    "exportable": true
  },
  "views": 100,
  "creatorId": "1",
  "createdAt": "2021-08-01T00:00:00Z",
  "updatedAt": "2021-08-02T00:00:00Z",
  "teamGuid": "123"
}

当前用户信息接口
提供一个公网可访问的 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：创建协同文档

POST 调用接口 https://office.shimoapi.com/sdk/v2/api/files ，
请求参数分为 query 和 body 两个部分。

query 参数包括：appId，signature，token。

appId：license 的 appId。

signature：签名算法算出的结果。

token：接入方提供的 token ，在石墨请求接入方的接口时，会放到 HTTP Headers X-Shimo-Token 中作为值进行传递。

body 使用 json 格式，参数包括：type，fileId。

type：documentPro

fileId：my-new-file-u98213

请求示例：

步骤 4：访问协同文档

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

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

手动创建

写一个最简单的 html 页面，包含一个父容器用来承载石墨的 iframe。

Shimo-js-sdk 地址：https://github.com/shimohq/shimo-js-sdk

使用 npm view 和 npm pack 下载代码包 (.tgz 格式).
命令行中输入：

会下载 shimo-js-sdk 的代码压缩包，例如 shimo-js-sdk-1.2.1.tgz。
解压这个文件，会得到名为 dist 的文件夹。

新建项目文件夹 shimo-doc-test。

将下载下来的代码包解压，并将 shimo-js-sdk 文件夹放在 shimo-doc-test 文件夹下。

在文件夹内新建两个文件，分别为 index.js 和 index.html，它们的内容如下：

index.js

index.html

新建一个文件夹叫 shimo-js-sdk，并将步骤 1 中得到的 dist 文件夹放入其中，此时目录结构如下：

shimo-doc-test/
├── index.js
└── index.html
└── shimo-js-sdk/
    └── dist/

双击用浏览器打开 index.html 文件，页面中将出现石墨的编辑器（iframe 方式挂载在配置的目标容器下），此时可编辑该协同文档。

步骤5：预览协同文档

保证获取文件元信息-协同文档回调返回的 permissions 中至少有可读权限

预览模式下都是只读，只关注是否可读，其他权限点不影响

iframe 访问访问预览 api地址

协同文档预览时无需创建预览，直接访问预览即可

预览内容同步协同编辑内容

协同编辑页面为 connect 后拼接的 /sdk/v2/collab-files/{fileId} 地址

预览页面为访问预览接口地址 /sdk/v2/api/cloud-files/{fileId}/page

编辑页内容更新后，刷新预览界面即会显示最新内容

协同文档流程图#

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

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

步骤 3：创建协同文档#

步骤 4：访问协同文档#

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

手动创建#

步骤5：预览协同文档#

预览内容同步协同编辑内容#