协同框架架构

架构设计

整体流程

核心组件

• 底层协同框架：实时协同的基础框架，处理客户端与服务器之间的通信和操作同步。

• 扩展包安装与绑定：协同服务的扩展包，为工作簿提供专用的 操作转换 (OT) 类型，包含 Reducer 和 Transform 逻辑，确保并发编辑时的数据一致性。

• 协同插件-快照与变更集：工作簿的插件，监听数据模型变化并生成操作 (ops)，将其整合到 ChangeSets 中与服务器交互，同时将服务器推送的 ChangeSets 应用到本地数据模型。

工作机制

• 本地同步：仅涉及 spread-sheets-collaboration-addon 插件，监控数据模型变化并在同一页面的多个工作簿实例间同步，无需服务器参与。

• 远程协同：spread-sheets-collaboration-addon 监听工作簿数据模型变化，生成对应操作并整合到 ChangeSets，通过 协同服务 框架传输至服务器。服务器利用 协同服务 的通信和处理能力，结合 spread-sheets-collaboration 中注册的 OT 类型（包含 Transform 和 Reducer 逻辑）处理操作，再将处理后的操作广播给所有连接的客户端，实现多用户实时协同。

应用场景

• 单用户多视图：使用 spread-sheets-collaboration-addon，同一页面的多个工作簿实例可操作同一文档，适用于需要不同视图或编辑视角的场景。

• 团队协同：配合 spread-sheets-collaboration，支持多用户实时编辑，适合团队共享和协同处理工作簿文档。

• 权限控制：可为不同用户分配编辑或只读权限。

功能概览

实时协同

• 多用户编辑：支持多人同时编辑同一工作簿文档，所有操作实时同步。

• 操作转换 (OT)：采用自定义 OT 类型，确保单元格更新、行插入等并发操作的一致性和正确性。

在线状态

• 用户标识：显示其他协同者的选区和姓名首字母，便于识别协同方工作区域。

• 自定义颜色：允许用户设置个性化颜色，提升不同协同者选区的可见性。

权限管理

• 编辑模式：用户可直接修改文档内容。

• 查看模式：用户仅能查看文档，无编辑权限。

本地同步

• 多实例同步：同一页面的多个工作簿实例可实时同步更新，适用于单用户多视图场景。

冲突处理行为

• 实时编辑状态：当冲突操作（如添加行、隐藏列）影响当前用户的编辑状态时，系统会更新编辑状态并确保用户界面（UI）正确显示。

内容导航

本章节各文档按读者关注度分组如下，可按需选读，无需通读。

快速了解

• 扩展包安装与绑定 — 客户端/服务端包的安装、OT_Type 注册、工作簿与文档的绑定。

协同模式与规则

• 协同模式 — 不同 SpreadJS 模型如何接入协同。下分两种模式：

  • 工作表模式 — 默认协作模式，基于工作簿快照同步。

  • 基于数据管理器的协作模式 — 集算表协作，详见 集算表。

• 冲突处理行为 — 多人编辑时冲突操作（插入/删除行列、隐藏、排序等）的内置处理行为。

• 协同规范 — 编写协同代码需遵循的约束（嵌套对象整体赋值、公式协同行为等）。

用户与权限

• 用户与权限 API — UserManager、setPresences/getPresences。

  • 活动状态 — 实时显示其他用户的光标与选区。

  • 权限类型 — 编辑模式与查看模式。

    • 设计器权限配置 — 设计器对查看模式权限的 UI 支持。

进阶参考

• 协同撤销机制 — 协同撤销机制、OT 转换后的撤销结果、四个协同撤销事件。

• 协同插件-快照与变更集 — 快照、变更集、批处理等底层 API。

  • 操作类型枚举 — 所有 OpType 枚举。

底层框架

上述能力均构建于 底层协同框架 之上。仅在自定义通信协议或在非 SpreadJS 场景中复用底层框架时，才需要直接阅读底层 API。