1.0.0

快速开始

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>
  • 静态资源由石墨托管

以 JS-SDK 形式接入

JS-SDK 形式相比 iframe 形式可以有更多定制性，可禁用一些组件或定制样式。

目前 JS-SDK 仅通过压缩包形式提供给用户，请于 JS-SDK 官方下载地址下载 JS-SDK Zip 压缩包，下载完毕后，将压缩包内的文件解压缩，将得到如下文件：

shimo-jssdk-1.0.0
├── shimo-sdk.sheet.editor-1.0.0.min.js
├── shimo-sdk.sheet.plugins.collaboration-1.0.0.min.js
├── shimo-sdk.sheet.plugins.collaborators-1.0.0.min.js
├── shimo-sdk.sheet.plugins.comment-1.0.0.min.js
├── shimo-sdk.sheet.plugins.contextmenu-1.0.0.min.js
├── shimo-sdk.sheet.plugins.historySidebar-1.0.0.min.js
├── shimo-sdk.sheet.plugins.sheetmenu-1.0.0.min.js
├── shimo-sdk.sheet.plugins.shortcut-1.0.0.min.js
├── shimo-sdk.sheet.plugins.toolbar-1.0.0.min.js
├── shimo.sdk.document.editor-1.0.0.min.js
├── shimo.sdk.document.plugins.collaborator-1.0.0.min.js
├── shimo.sdk.document.plugins.comment-1.0.0.min.js
├── shimo.sdk.document.plugins.demo-screen-1.0.0.min.js
├── shimo.sdk.document.plugins.gallery-1.0.0.min.js
├── shimo.sdk.document.plugins.history-1.0.0.min.js
├── shimo.sdk.document.plugins.mention-1.0.0.min.js
├── shimo.sdk.document.plugins.revision-1.0.0.min.js
├── shimo.sdk.document.plugins.table-of-content-1.0.0.min.js
├── shimo.sdk.document.plugins.uploader-1.0.0.min.js
├── shimo.sdk.common.collaboration-1.0.0.min.js
└── shimo.sdk.common.common-1.0.0.min.js

以上仅供参考，实际文件和版本号以 JS-SDK 具体版本为准。

  • 以 shimo.sdk.common 开头的文件为通用文件，需要优先加载
  • 以 shimo.sdk.document 或 shimo.sdk.sheet 开头的文件为对应格式文档的专用文件，如 sheet 值表格，可按需加载
  • 您需自行托管静态资源

将以上文件放至到项目的静态资源目录下，以下以构建一个文档（document）编辑器为例。

假设项目目录结构如下：

example
├── index.html
└── js
    ├── main.js
    ├── shimo.sdk.document.editor-1.0.0.min.js
    ├── shimo.sdk.document.plugins.collaborator-1.0.0.min.js
    ├── shimo.sdk.document.plugins.comment-1.0.0.min.js
    ├── shimo.sdk.document.plugins.demo-screen-1.0.0.min.js
    ├── shimo.sdk.document.plugins.gallery-1.0.0.min.js
    ├── shimo.sdk.document.plugins.history-1.0.0.min.js
    ├── shimo.sdk.document.plugins.mention-1.0.0.min.js
    ├── shimo.sdk.document.plugins.revision-1.0.0.min.js
    ├── shimo.sdk.document.plugins.table-of-content-1.0.0.min.js
    ├── shimo.sdk.document.plugins.uploader-1.0.0.min.js
    ├── shimo.sdk.common.collaboration-1.0.0.min.js
    └── shimo.sdk.common.common-1.0.0.min.js

index.html：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Example</title>
    <script crossorigin src="https://unpkg.com/axios/dist/axios.min.js"></script>
    <script src="/js/shimo.sdk.common.common-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.common.collaboration-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.editor-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.table-of-content-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.history-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.uploader-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.collaborator-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.gallery-1.0.0.min.js"></script>
    <script src="/js/shimo.sdk.document.plugins.comment-1.0.0.min.js"></script>
  </head>
  <body>
    <div id="toolbar-wrapper" class="toolbar-wrapper"></div>
    <div id="editor-scroller" class="editor-scroller">
      <div id="editor"></div>
    </div>

    <script src="/js/main.js"></script>
  </body>
</html>

main.js：

async function main () {
  const fileGuid = '<GUID>'

  const { data: token } = await axios({
    url: '<SHIMO_API>/entry/oauth2/token',
    method: 'post',
    data: {
      clientId: '<CLIENT_ID>',
      clientSecret: '<CLIENT_SECRET>',
      clientUserId: '<CLIENT_USER_ID>',
      grantType: 'client_credentials',
      scope: 'write',
      info: JSON.stringify({
        fileGuid: fileGuid,
        filePermissions: {
          editable: true,
          readonly: true,
          commentable: true
        }
      })
    }
  })

  const { data: user } = await axios({
    url: '<SHIMO_API>/users/me',
    headers: {
      authorization: `Bearer ${token.accessToken}`
    }
  })

  const shimo = window.shimo
  Object.assign(shimo, {
    token: token.accessToken,
    uploadToken: token.uploadToken
  })

  // 初始化编辑器
  const Editor = shimo.sdk.document.Editor
  const editor = new Editor({ theme: 'shimo' })
  editor.render(document.querySelector('#editor'), {
    id: user.id,
    scrollingContainer: document.querySelector('#editor-scroller'),
    modules: {
      toolbar: {
        parent: document.querySelector('#toolbar-wrapper')
      }
    }
  })

  const { data: file } = await axios.get(`<SHIMO_API>/files/${fileGuid}`, {
    headers: {
      Authorization: `Bearer ${token.accessToken}`
    }
  })

  const collaboration = window.collaboration = new shimo.sdk.common.Collaboration({
    editor,
    type: 'richdoc',
    // 文档版本号
    rev: file.head,
    // 文档 id 或者 guid
    guid: file.guid,
    // 文档获取改动的地址
    pullUrl: `<SHIMO_API>/files/${file.guid}/pull?accessToken=${shimo.token}`,
    storage: { set () {} },
    // 文档提交改动地址
    composeUrl: `<SHIMO_API>/files/${file.guid}/compose?accessToken=${shimo.token}`
  })

  const Collaborator = new shimo.sdk.document.plugins.Collaborator({
    editor,
    user: {
      id: user.id,
      name: user.name,
      avatar: user.avatar
    },
    service: {
      user: `<SHIMO_API>/users?accessToken=${shimo.token}&_legacy=1`
    },
    avatarTrack: true,
    cursorTrack: true
  })
  collaboration.start()
  Collaborator.render(collaboration)

  editor.setContent(file.content)
}
main()

在浏览器上效果如图：