快速开始
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()
在浏览器上效果如图: