[]
SpreadJS 协同规范本手册介绍 SpreadJS 协作模式下的行为规则与使用规范。相关机制用于控制共享工作簿环境中多个客户端之间的实时同步逻辑。
帮助开发者明确客户端间变更同步的时机与方式。
定义修改样式、打印设置及其他嵌套对象的正确方法。
说明公式计算、同步规则及迭代计算时的行为规范。
对嵌套对象执行直接本地修改，不会在客户端间同步。
如需同步更新，必须通过赋值方法对整个对象进行重置或重新赋值。
场景 | 本地效果 | 同步行为 | 推荐操作 |
|---|---|---|---|
修改 | 仅当前客户端可见样式更新 | 变更不会同步至其他客户端 | 使用 |
修改 | 仅影响本地视图 | 不会同步 | 通过完整赋值方法重新指定打印设置（如 |
触发正确同步的步骤：
获取待修改的对象。
在本地完成更新。
调用赋值方法，将更新后的完整对象重新应用至工作表或工作簿。
示例：
// 错误写法——无法同步
let s = sheet.getStyle(1, 1);
s.backColor = "yellow"; // 仅本地生效
// 正确写法——可同步
let style = sheet.getStyle(1, 1);
style.backColor = "yellow";
sheet.setStyle(1, 1, style); // 触发协作同步公式在协作模式下具有特殊行为。各客户端基于共享的公式定义，独立执行计算并维护本地状态。
快照中仅存储公式表达式。
公式计算结果不会被存储，也不会在客户端间同步。
工作簿加载时，各客户端独立重新计算公式。
因执行顺序或迭代计算差异，计算结果可能临时不一致。
协作服务仅同步公式编辑操作（插入、删除、修改）。
计算结果（数值输出）不进行传输与同步。
各客户端独立维护自身 CalculationMode（手动或自动）。
单个客户端的计算模式变更不会影响其他客户端或服务端。
遵循以下原则：
按常规方式编写公式（如 =A1 + B1）。
避免依赖存储结果——各客户端会独立重新计算。
谨慎使用迭代或易变函数（RAND、NOW 等），此类函数在不同客户端的计算结果可能不一致。
分类 | 说明 | 公式示例 | 同步行为 |
|---|---|---|---|
自收敛型 | 迭代至结果稳定，所有客户端结果一致 | 部门成本相互分摊计算 | 客户端间结果一致，刷新后无变化 |
非收敛型 | 无限迭代或结果不稳定 |
| 客户端结果不一致，刷新后重置 |
自动数据录入（单次迭代） | 仅执行一次迭代（如时间戳） |
| 各客户端时间戳独立，刷新后重置 |
若用户通过 workbook.collaboration.onChangeSet 注册变更集监听器，SpreadJS 即判定为进入协作状态。
当 SpreadJS 处于协作模式时，受协作数据同步机制影响，部分接口将失效（无执行效果）。
接口所属对象 | 接口名称 |
|---|---|
Workbook | fromJSON |
Workbook | import |
Workbook | open |
Worksheet | reset |