锁定

支持创建工作表锁和范围锁，实现细粒度的内容权限控制。

构造函数

• 用法

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。