快速开始 · 石墨文档协同编辑 SDK

Shimo-JavaScript-SDK（下文简称为 JS-SDK）用于在浏览器环境查看及编辑石墨文档数据，JS-SDK 需结合石墨文档官方 API 使用。

事前准备

在开始之前，请确保你已完成以下准备：

在使用 JS-SDK 之前，您须向石墨文档申请 ClientId 和 ClientSecret，以作为鉴权依据，详情请参阅 API 文档
满足 JS-SDK 运行所需的浏览器环境
- Chrome、IE 11、Firefox、Microsoft Edge、Safari 等现代浏览器
本页面中所有代码均基于 JavaScript，服务器端部分需要 node.js 环境，您可根据需要选用其他语言环境
若您在使用石墨文档测试服务，则额外需要可连接至石墨文档的网络

约定事项：

<SHIMO_API> 指石墨 SDK API 的入口，和 API 文档保持一致
- 测试环境为：https://platform.shimodev.com/entry
- 正式环境为：https://platform.shimo.im/entry
<CLIENT_ID> 和 <CLIENT_SECRET> 为分配给您的认证用凭证
<CLIENT_USER_ID> 为您内部标识用户用的唯一 ID，一般为数字 ID、电子邮箱或手机号码
<ACCESS_TOKEN> 为您通过 <CLIENT_ID> 和 <CLIENT_SECRET> 申请的 Access Token
为石墨为创建的文档分配的唯一 ID
如无特殊说明，所有请求均基于 Content-Type: application/json，请根据所使用的 HTTP 请求库添加对应的 header

接入石墨 SDK

申请 Access Token

Access Token 是与 API 通信的凭证，并且和文档一一对应，因此访问不同文档时需要申请不同 Access Token。

为了保障信息安全，请通过您的服务器程序申请 Access Token。

const axios = require('axios')

const token = (await axios({
  url: `<SHIMO_API>/oauth2/token`,
  method: 'post',
  body: {
    clientId: '<CLIENT_ID>',
    clientSecret: '<CLIENT_SECRET>',
    clientUserId: '<CLIENT_USER_ID>',
    grantType: 'client_credentials',
    scope: 'write',
    info: '' // 额外的权限信息，用于访问文档时使用，详见 API 文档
  }
})).data

返回示例：

{
  "scope": "write",
  "tokenType": "bearer",
  "accessToken": "<ACCESS_TOKEN>",
  "refreshToken": "<REFRESH_TOKEN>",
  "expireTime": "2018-06-12T09:50:23.000Z"
}

创建文档

const axios = require('axios')

const file = (await axios({
  url: `<SHIMO_API>/files`,
  method: 'post',
  body: {
    type: 'document',
    name: 'my title'
  },
  headers: {
    Authorization: `Bearer <ACCESS_TOKEN>`
  }
})).data

返回示例：

{
  "head": 1,
  "guid": "<GUID>",
  "type": "document",
  "content": ""
}

以 iframe 形式接入

石墨 SDK 提供 iframe 的接入方式，方便在任何 HTML 页面嵌入石墨文档，适合无定制性要求的场景。

<!DOCTYPE html>
<html>
  <body>
    <iframe src="<SHIMO_API>/view/<GUID>?accessToken=<ACCESS_TOKEN>"></iframe>
  </body>
</html>

静态资源由石墨托管

iframe 形式在私有部署版中不可用。

以 JS-SDK 形式接入

JS SDK 接入方式请参考官方 GitHub 项目：shimohq/sdk-cabinet。