【SpreadJS V18.2 新特性】新插件：表格协同

SpreadJS V18.2 新推出的协同插件介绍

SpreadJS V18.2 版本引入了全新的 SpreadJS Sheets Collaboration Add-on（以下简称“协同插件”），这是一个专为 JavaScript 电子表格设计的协作扩展模块。

该插件基于 SpreadJS 的协作框架（Collaboration Framework）构建，旨在为团队、企业应用或嵌入式 SaaS 工具提供无缝的实时编辑体验，类似于 Excel for Web 或 Google Sheets 中的功能。

目前，该插件处于 beta 版本，预计将在年内正式发布，并可能根据用户反馈进行优化。

通过该插件，开发者可以轻松地将多用户协作集成到电子表格应用中，消除同步延迟、简化用户交互，并减少维护数据一致性的复杂性。

协同插件的组成架构

SpreadJS V18.2 的协同功能基于 “协同框架（Collaboration Framework）” 和 “表格协同插件（Sheets Collaboration Add-on）” 构建，形成模块化、可扩展的实时协作体系，具体组成如下：

1.协同框架（Collaboration Framework）

作为底层核心，支持多种文档类型（表格、富文本、代码编辑器等）的高性能、低延迟协作，包含三大核心模块：

• js-collaboration：处理实时双向数据交换、可扩展的消息广播，实现用户间的即时同步

• js-collaboration-ot：基于操作转换（OT）的冲突解决逻辑，集成数据库适配器，确保多用户并发编辑时的数据一致性

• js-collaboration-presence：提供用户存在感知功能，如显示活跃用户的光标、选区，支持协同编辑的视觉化提示

2.表格协同插件（Sheets Collaboration Add-on）

基于协同框架针对表格场景优化，提供即插即用的多用户编辑能力，包含两个核心包：

• spread-sheets-collaboration：定义表格特有的 OT 类型，包括状态合并的归约逻辑、并发冲突的转换逻辑

• spread-sheets-collaboration-addon：增强工作簿的协同能力，如检测本地修改并转换为操作集（Ops）、将 Ops 分组为 ChangeSet、应用外部 ChangeSet 以同步用户视图等

主要能力

协同插件（spread-sheets-collaboration-addon）通过集成操作变换（Operational Transformation, OT）技术、ChangeSet 机制和用户存在感知功能，实现了高效的实时协作。以下是其核心能力：

1.实时协作编辑与冲突解决：

• 支持多用户同时编辑同一工作簿，实现即时更新和双向数据交换

• 使用 OT 逻辑处理并发编辑，确保无冲突合并，例如当多个用户修改同一单元格时，系统会自动转换操作以保持数据一致性

• 检测本地工作簿变化，将其转换为操作（Ops）并分组为 ChangeSet，然后通过服务器广播同步到所有客户端

2.用户存在感知和 UI 增强：

• 显示活动用户的光标和选择区域，提供协作意识的 UI 元素，帮助用户实时感知他人操作

• 支持自定义用户认证、访问控制和版本跟踪，适用于不同文档类型（如电子表格、富文本编辑器）

3.权限管理：

• 配置查看模式（View Mode）和编辑模式（Edit Mode），查看模式限制为只读访问（允许本地 UI 交互如排序或调整大小），编辑模式支持完整同步编辑

/**
 * 枚举用于文档交互的浏览模式。
 * @enum {number}
 */
export enum 浏览模式 {
    /** 允许用户编辑文档。
     * @type {number}
     */
    编辑,
    /** 限制用户只能查看文档。
     * @type {number}
     */
    查看,
}

• 允许开发者根据用户角色实现细粒度权限控制，平衡协作与数据完整性

4.协作撤销/重做支持：

• 撤销栈以 Ops 形式存储变化，确保所有撤销动作在客户端间同步

• 仅影响用户自身操作，不干扰他人；外部操作到达时，会转换撤销结果以适应更新上下文

• 提供四个事件（CollaborationStartUndo、CollaborationEndUndo、CollaborationStartRedo、CollaborationEndRedo）供开发者自定义处理 UI 和状态变化

• 注意：在协作模式下，命令的 do/undo/redo 通过 Ops 执行，而非传统命令逻辑

5.协作编辑状态处理：

• 内置功能跟踪实时编辑状态，防止冲突（如行删除、列隐藏、排序导致的覆盖）

• 支持冲突操作处理，包括添加/删除行/列、隐藏行/列、排序和调整行高/列宽

• 视觉指示状态变化（如“Deleted”、“A1(Hidden)”或新单元格引用），并在编辑完成后决定是否写入值（例如，删除状态下不写入）

• 支持状态反转：对于非删除操作，如果引起变化的动作被撤销，状态会相应恢复；删除状态不自动反转，以确保内容一致性

ChangeSet 和批量操作：

• ChangeSet 是相关 Ops 的集合，代表一个逻辑修改单元，支持原子性应用、冲突解决、历史跟踪和性能优化

• 默认单模式下，每个命令生成一个 ChangeSet；批量模式允许合并多个同步操作，减少服务器负载

• API 支持：applyChangeSet 应用 ChangeSet，onChangeSet 监听生成；startBatchOp 和 endBatchOp 用于批量分组（必须成对使用，且操作需同步）

interface IChangeSet {
    ops: IOpComponent[];
}
/**
 * 仅用于协同场景，将变更集应用到文档。
 * @param {changeSet: GC.Spread.Sheets.Collaboration.IChangeSet} changeSet - 变更集
 */
Workbook.collaboration.prototype.applyChangeSet = (changeSet: GC.Spread.Sheets.Collaboration.IChangeSet) => void;

/**
 * 仅用于协同场景，监听变更集。
 * @param {changeSetHandler: GC.Spread.Sheets.Collaboration.IChangeSetHandler} onOpHandler - 监听变更集的回调
 */
Workbook.collaboration.prototype.onChangeSet = (onChangeSetHandler: GC.Spread.Sheets.Collaboration.IChangeSetHandler) => void;

• 限制：仅适用于源自同一快照的工作簿

当前限制

协同不支持的功能：

• 所有绑定相关功能（表格级绑定、工作表级绑定、单元格级绑定）

• 所有数据管理器相关功能（数据图表、甘特表、集算表、报表）

• 浮动对象和旧版图表

应用价值

提升团队协作效率

支持分布式团队实时共同编辑表格（如项目计划、财务报表、数据汇总），消除版本混乱和沟通延迟，缩短任务完成周期。

适配企业级场景

满足企业级应用的核心需求：

• 多人评审场景： stakeholders 可实时查看并追踪修改，通过光标和选区明确讨论焦点

• 审计与版本追溯：结合 ChangeSet 的历史记录，实现操作溯源和版本回滚，满足合规性要求

• 权限管控：基于角色的访问控制（如只读 / 编辑权限）确保敏感数据安全

降低开发复杂度

开发者无需从零构建协同逻辑，通过插件提供的 API（如applyChangeSet、onChangeSet）快速集成实时协作功能，专注于业务场景而非底层同步机制

优化用户体验

冲突自动处理、编辑状态实时提示等功能，减少用户操作失误和认知负担，让协同编辑更流畅自然

总体而言，该插件为开发者提供了生产就绪的基础设施，帮助构建现代、直观的电子表格应用。如果您想深入了解，请参考 SpreadJS 产品文档，或通过在线演示进行测试。