锁定
支持创建工作表锁和范围锁,实现细粒度的内容权限控制。
构造函数
- 用法
const editor = new window.shimo.sdk.sheet.Editor()
const lockPlugin = new window.shimo.sdk.sheet.plugins.Lock({
editor: editor,
currentUser: { id: 12345 },
// 当前用户对当前文件的权限配置, 说明见PermissionConfig
// 需要注意的是这里的权限配置并不是锁定数据,锁定数据完全由sdk内部来处理,外部无需关心
permission: {
read: true,
edit: true,
comment: true,
lock: true,
manage: false,
},
fetchCollaborators: async function () { return [ {id:12345, ...} ] },
fetchUserUrl: '/api/users/{userId}'
})
- 参数
名称 | 类型 | 默认值 | 描述 |
---|---|---|---|
options.editor | Editor | 必选 | 编辑器实例 |
options.currentUser | { id: number } | 必选 | 当前用户 |
options.permission | PermissionConfig | 必选 | 用户对当前文件的权限配置(下面详细说明) |
options.fetchCollaborators | string 或 () => Promise<Collaborator[]> | 必选 | 获取文件协作者列表的 URL 或异步方法 |
options.fetchUserUrl | string | 非必选 | 获取锁定者信息URL,若不传则锁定侧边栏不会展示锁定者信息 |
/** 权限配置 */
interface PermissionConfig {
/** 是否允许读 */
read: boolean
/** 是否允许修改 */
edit: boolean
/** 是否允许评论 */
comment: boolean
/**
* 是否允许操作工作表锁和范围锁
*
* 启用后,将允许用户创建锁,以及编辑、删除自己创建的锁,
* 但不允许修改、删除他人创建的锁(除非具备管理者权限)
*/
lock: boolean
/**
* 是否具备文件管理者权限
*
* - 默认允许读、修改、评论
* - 允许编辑、删除其他用户创建的锁 (*存在例外)
* - 不会被锁
* - 创建新锁时,无法将管理者锁定为「只读」或「不可见」权限
* - 已有的锁不对当前用户生效 (*存在例外)
*
* (*): 如果已有的锁对该用户计算为「不可见」权限时,则依然生效(内容不可见,锁不可编辑、不可删除)
*/
manage: boolean
}
/** 协作者 */
interface Collaborator {
/** ID */
id: number
/** 邮箱 */
email?: string
/** 头像图片url */
avatar?: string
/** 姓名 */
name: string
/** 姓名拼音, 如"yonghu|'yong'hu", 用于锁定对话框中列表过滤 */
namePinyin?: string
/** 对当前文件的权限配置 */
permission: PermissionConfig
/**
* 对当前文件的角色
* 可以是任意文本,如'管理员','所有者', '创建者' 等,用于锁定对话框中用户身份展示,不用于权限判断
*/
displayRole?: string | undefined
}
- fetchUserAPI 返回结果
interface UserInfo {
id: number
name: string
namePinyin?: string
email: string
avatar: string
}
方法列表
如何获取协作者列表
自定义函数
在初始化插件时,传入一个 fetchCollaborators
函数,该函数返回一个 Promise
,结果是协作者数组。
const lockPlugin = new window.shimo.sdk.sheet.plugins.Lock({
editor: editor,
currentUser: { id: 12345 },
// 用户对当前文件的权限配置,详见PermissionConfig
// 需要注意的是这里的权限配置并不是锁定数据,锁定数据完全由sdk内部来处理,外部无需关心
permission: {
read: true,
edit: true,
comment: true,
lock: true,
manage: false,
},
fetchCollaborators: function () {
return Promise.resolve([{
"id": 1,
"name": "shimodev",
"namePinyin": null,
"email": "shimodev@shimo.im",
"avatar": "https://assets-cdn.shimo.im/static/unmd5/default-avatar-moke.png",
"permission": {
"read": true,
"edit": true,
"comment": true,
"lock": true,
"manage": true
}
}])
},
fetchUserUrl: '/api/users/{userId}'
})
通过 API
const lockPlugin = new window.shimo.sdk.sheet.plugins.Lock({
editor: editor,
currentUser: { id: 12345 },
permission: {
read: true,
edit: true,
comment: true,
lock: true,
manage: false,
},
fetchCollaborators: 'https://domain.com/path/to/collaborators'
})
石墨 SDK 会通过 GET 请求该 API 地址,该 API 地址返回协作者数组。
石墨私有部署版本内置一个 API:
const lockPlugin = new window.shimo.sdk.sheet.plugins.Lock({
editor: editor,
currentUser: { id: 12345 },
permission: {
read: true,
edit: true,
comment: true,
lock: true,
manage: false,
},
fetchCollaborators: '<SHIMO_API>/files/<GUID>/collaborators?accessToken=<ACCESS_TOKEN>'
})
Access Token 需通过 querystring 形式传递。
详见获取协作者 API。