文档
基本数据结构
字段名 | 类型 | 说明 |
---|---|---|
type | String | 见下表 |
head | Number | 文档的当前版本号,协同编辑场景下,此版本号会随着每次编辑递增 |
content | String | 文档的内容,格式为专用格式 |
type 类型 | 说明 |
---|---|
document/richdoc | 新文档 |
document/modoc | 专业文档 |
sheet/modoc | 表格 |
slide/modoc | 幻灯片 |
创建文档
接口
POST <SHIMO_API>/files
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
type | String | Y | 文档类型,类型列表见下方 |
name | String | N | 文档标题,默认 无标题 |
copy | Boolean | N | 不为空时代表该文档是拷贝自其他文档,仅影响历史的创建,不是对其他文档进行复制 |
content | string | N | 文档的默认内容,需要以石墨格式的形式传递 |
type
类型:
类型 | 说明 |
---|---|
document | 新文档 |
documentPro | 专业文档,别名 modoc 。 |
sheet | 表格,别名 spreadsheet 。 |
slide | 幻灯片 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({ type: 'document' })
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"head": 1,
"guid": "JyRX1679PL86rbTk",
"type": "document",
"content": "shimo content"
}
获取文档
接口
GET <SHIMO_API>/files/<GUID>
鉴权信息
参数 | 说明 |
---|---|
scope | "read" |
info.fileGuid | <GUID> |
info.filePermissions.readonly | true |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
content | String | N | 为 plain 时,将会把 file.content 从石墨专有格式转换为纯文本返回 |
withConfig | Boolean | N | 服务器返回内容时,同时返回用于初始化编辑器的配置,会放置在 config 字段下 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk', {
method: 'GET',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
.then(res => res.json())
.then(body => console.log(body.data))
返回示例
{
"head": 1,
"guid": "JyRX1679PL86rbTk",
"type": "document",
"content": "shimo content"
}
更改文档标题
对于私有部署版本,此接口仅用于生成用户更改标题的历史,并不保存实际的文件标题。
接口
PATCH <SHIMO_API>/files/<GUID>/title
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
info.fileGuid | <GUID> |
info.filePermissions.editable | true |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
name | String | Y | 新的文档标题 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/title', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({ name: 'new document name' })
})
.then(res => res.json())
.then(body => console.log(body.data))
状态码说明
204
操作成功
还原文档
接口
POST <SHIMO_API>/files/<GUID>/revert
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
info.fileGuid | <GUID> |
info.filePermissions.editable | true |
参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
docHistoryId | Number | Y | 待还原的历史 ID |
before | String | N | 值为 true / false |
startTimestamp | Number | N | 该次改动发生的时间 |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/revert', {
method: 'POST',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"docHistoryId": 478035
})
})
状态码说明
204
操作成功
删除文档和相关内容
接口
DELETE <SHIMO_API>/files/<GUID>
删除文档会连同历史等记录一起删除,不可恢复
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
info.fileGuid | <GUID> |
info.filePermissions.editable | true |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk', {
method: 'DELETE',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
状态码说明
204
操作成功
在线用户列表
接口
GET <SHIMO_API>/files/<GUID>/online
clients 对应同一个用户打开的多个 tab 页
鉴权信息
参数 | 说明 |
---|---|
scope | "write" |
info.fileGuid | <GUID> |
info.filePermissions.editable | true |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/online', {
method: 'GET',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
返回示例
[
{
"user":
{
"id":13249,
"avatar":"https://avatars3.githubusercontent.com/u/13383310?s=70&v=4",
"name":"tom"
},
"clients":[
{
"clientId":"6b310abfe3ab43d8977342de9f6f870f"
}
]
},
{
"user":
{
"id":13250,
"avatar":"https://avatars0.githubusercontent.com/u/1641516?s=96&v=4",
"name":"lucy"
},
"clients":[
{
"clientId":"67d30248feaa4d73871299aad149e2ce"
}
]
}
]
获取协作者列表
此接口用于表格单元格锁定,目前只用于私有部署版本。
需要在后端部署 API 回调接口。
接口
GET <SHIMO_API>/files/<GUID>/collaborators
鉴权信息
参数 | 说明 |
---|---|
scope | "read" |
info.fileGuid | <GUID> |
info.filePermissions.readable | true |
代码示例
const request = require('node-fetch')
fetch('<SHIMO_API>/files/JyRX1679PL86rbTk/collaborators', {
method: 'GET',
headers: {
Authorization: 'Bearer <Access Token>',
'Content-Type': 'application/json'
}
})
接入说明:
需要在后端配置 FILE_COLLABORATORS_API
,在请求此接口时,石墨服务会向 FILE_COLLABORATORS_API
发起 POST 请求,带上 fileGuid
和 clientUserId
参数,FILE_COLLABORATORS_API
需以 application/json
和数组形式返回协作者列表,返回数据格式:
[
{
"clientUserId": "shimodev",
"permissions": {
"read": true,
"edit": true,
"comment": true,
"lock": true,
"manage": true
}
}
]
石墨后端会以此结果做二次封装。
每个用户的权限需要以
permissions
字段声明。
返回示例
[{
"id": 1,
"name": "shimodev",
"namePinyin": null,
"email": "shimodev@shimo.im",
"avatar": "https://assets-cdn.shimo.im/static/unmd5/default-avatar-moke.png",
"status": 0,
"createdAt": "2019-03-10T07:35:41.000Z",
"updatedAt": "2019-07-15T02:11:38.000Z",
"deletedAt": null,
"clientUserId": "shimodev",
"permission": {
"read": true,
"edit": true,
"comment": true,
"lock": true,
"manage": true
}
}]