文档 · 石墨文档协同编辑 SDK

基本数据结构

字段名	类型	说明
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
  }
}]