开发工具

10 分钟创建协同文档

快速创建一个 word 文档，并在石墨编辑器中使用。

步骤 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

请求示例：

curl --location --request POST 'https://office.shimoapi.com/sdk/v2/api/files?appId=yourShimoAppId&signature=yourSignatureString&token=yourTokenString' \
--header 'Content-Type: application/json' \
--data-raw '{"type": "document","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 格式).
命令行中输入：

npm view shimo-js-sdk
npm pack shimo-js-sdk

会下载 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

const { connect, FileType } = window.ShimoJSSDK;
const fileId = "my-new-file-u98213"; // 刚才定义的文件id

// const { signature, token } = await getCredentialsFromServer() // 从您的后端服务获取用于石墨鉴权的签名和 token
const signature = "{your-calculated-signature}"; // 测试时直接写在这里
const token = "{your-customized-token}"; // 测试时直接写在这里

connect({
  debug: true,
  fileId: fileId,
  endpoint: "https://office.shimoapi.com/sdk/v2",
  signature: signature,
  token: token,
  container: document.querySelector("#iframe-container"), // iframe 挂载的目标容器元素id
}).then((sdk) => {
  // sdk 即为 ShimoSDK 实例
  // console.log(sdk)
});

index.html

<head>
  Hello Shimo
</head>
<div id="iframe-container"></div>
<script src="./shimo-js-sdk/dist/index.js"></script>
<script src="index.js"></script>

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

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

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

最后修改时间： 8 个月前