讯飞文档开发者中心

# 协同编辑

协同模块通过和服务器建立 WebSocket 通信，实现多人实时协同编辑功能。该模块需要后端服务支持。

生产环境的 WebSocket URL 是 wss://openapi.iflydocs.com，其他环境请参考 服务环境。

协同模块中可以通过配置网络在线状态来实现离线编辑功能。业务方需要监听 save-offline-ops 事件和 save-doc-content 事件，用于存储离线状态编辑产生的增量数据和存储文档全量的内容。后续可以通过 离线上传内容 将离线期间产生的数据同步到服务端。

协同模块需单独引入 collboration.js。

# 构造函数

  • 定义
constructor(
  editor: Editor,
  options: {
    wsURL: string
    token: string
    fid: string
    sid: string
    //onlineStatus
    mode: 'online' | 'offline'
    offlineOps: Object[] | null
    cacheContent: Delta | null
    saveDelay?: number
  }
)
  • 参数
    • edtior: 编辑器对象。
    • options: 选项。
      • wsURL: 协作服务 WebSocket URL。
      • token: 用户授权令牌，参考: 获取用户令牌。
      • fid: 文档 ID，参考: 创建文档。
      • sid: 协作会话 ID，同一个用户使用不同客户端协作，应使用不同的协作会话 ID。推荐使用 UUID。
      • mode: 编辑器模式。
        • online: 在线模式，正常协同。
        • offline: 离线模式，编辑产生的数据不会协同，而是缓存起来。
      • offlineOps: 离线编辑的增量 OP 数据。没有历史离线编辑数据时传 null。
      • cacheContent: 本地缓存的全量文档内容，用于正确展示离线编辑后的文档。无内容是传 null。
      • saveDelay: 可选，默认 300ms。保存防抖动时间间隔。

# 实例方法

# getMode()

  • 功能

获取编辑器网络模式。

  • 定义
// aka getOnlineStatus
getMode(): 'online' | 'offline'
  • 参数

无。

  • 返回

编辑器的网络模式，在线或者离线。

# setMode()

  • 功能

设置编辑器网络模式。

当网络在线状态发生变化时，需要调用此方法设置编辑器网络模式，以获得最佳编辑体验。

  • 定义
// aka setOnlineStatus
setMode(mode: 'online' | 'offline')

  • 参数

    • mode: 模式
      • online: 在线模式
      • offline: 离线模式

  • 返回

无。

# getOfflineOps()

  • 功能

获取离线编辑期间产生的增量数据。

  • 定义
getOfflineOps(): Object[] | null
  • 参数

无。

  • 返回
    • 离线模式下返回 OP 数组。
    • 在线模式下返回 null。

# setFid()

  • 功能

设置文档 ID，具体请参考《离线创建》。

  • 定义
setFid(fid: string)

  • 参数

    • fid: 文档 ID。

  • 返回

无。

# setToken()

  • 功能

设置（更新）用户令牌。

  • 定义
// aka refreshToken
setToken(token: string)

  • 参数

    • token: 用户令牌。

  • 返回

无。

# revert()

  • 功能

还原到指定的历史版本。

通过协同服务实现，与本地历史的撤回和重做不一样。具体请参考：《历史记录》。

  • 定义
// aka docRevert
revert(version: number)

  • 参数

    • version: 历史版本号。

  • 返回

无。

# 事件

# connection-success

  • 说明

协同链接简历成功。

  • 定义
// aka collaboration-success
on(event: 'connection-success', handler: () => void)
once(event: 'connection-success', handler: () => void)
off(event: 'connection-success', handler: () => void)
  • 参数

无。

  • 返回

无。

# connection-error

  • 说明

协同链接出错。

不一定是建立出错。建立成功后，使用过程中仍可能出错。

可以处理一些页面的 loading 等事宜。

  • 定义
// aka sharedb-connection-error
on(event: 'connection-error', handler: (error: Error) => void)
once(event: 'connection-error', handler: (error: Error) => void)
off(event: 'connection-error', handler: (error: Error) => void)

  • 参数

    • error: 错误对象，包含出错具体信息，错误码、原因等。

  • 返回

无。

# permission-change

  • 说明

文档权限发生变更。

比如从可编辑变为只读，需要客户端处理编辑器的可编辑状态等。

  • 定义
on(event: 'permission-change', handler: () => void)
once(event: 'permission-change', handler: () => void)
off(event: 'permission-change', handler: () => void)
  • 参数

//TODO:

待完善

  • 返回

无。

# token-invalid

  • 说明

用户令牌失效。

客户端需获取最新的 token，并调用 setToken 更新令牌，重新建立连接。

  • 定义
// aka ws-refresh-token
on(event: 'token-invalid', handler: () => void)
once(event: 'token-invalid', handler: () => void)
off(event: 'token-invalid', handler: () => void)
  • 参数

无。

  • 返回

无。

# save-offline-ops

  • 说明

离线编辑时，会触发此事件，事件回调参数是离线产生的增量数据。客户端需妥善保存，并在合适的时机，通过 离线上传内容 将离线期间产生的数据同步到服务端。

  • 定义
on(event: 'save-offline-ops', handler: (ops: Object[]) => void)
once(event: 'save-offline-ops', handler: (ops: Object[]) => void)
off(event: 'save-offline-ops', handler: (ops: Object[]) => void)

  • 参数

    • ops: OP 数组。

  • 返回

无。

# save-doc-content

  • 说明

文档内容变化时触发此事件，事件回调参数是文档全量的数据，可保存至本地。

如果需要实现离线编辑功能，无论网络是在线还是离线，都需要监听此事件，保存数据。

  • 定义
on(event: 'save-doc-content', handler: (doc: Delta) => void)
once(event: 'save-doc-content', handler: (doc: Delta) => void)
off(event: 'save-doc-content', handler: (doc: Delta) => void)

  • 参数

    • doc: 文档全量数据。

  • 返回

无。

# revert-success

  • 说明

用户历史记录还原成功。

  • 定义
// aka docRevertSuccess
on(event: 'revert-success', handler: () => void)
once(event: 'revert-success', handler: () => void)
off(event: 'revert-success', handler: () => void)
  • 参数

无。

  • 返回

无。

# revert-error

  • 说明

用户历史记录还原成功。

  • 定义
// aka docRevertError
on(event: 'revert-error', handler: () => void)
once(event: 'revert-error', handler: () => void)
off(event: 'revert-error', handler: () => void)
  • 参数

无。

  • 返回

无。

← 工具类函数 →