历史记录
回看历史版本、定位内容变化,并将选定版本恢复到当前共享文档。
历史记录把已协同确认的修改组织成可浏览的版本。每条已确认的修改都带有作者、时间和操作,开发者和用户可以据此打开当时的内容、查看差异,并在有权限时恢复某个版本。历史记录不随编辑会话结束而消失,刷新页面后仍然可以查看。
历史记录的原理
Mutation 是一条可以重放的内容变更,例如修改单元格或插入段落。Changeset 是一次协同提交,包含一组按顺序排列的 Mutation。
1. 记录变更
用户或 Agent 的每次编辑都会产生 Mutation。Univer 把这些 Mutation 打包成一个 Changeset 提交,由协同服务确认并保存。
提交确认后会获得一个 Revision(修订号),用来标识这次提交在文档历史中的位置。History 为已确认的 Changeset 建立索引,按时间和操作分组,并构建版本时间线。
2. 重建历史内容
Snapshot(快照) 是某个 revision 对应的完整内容状态。选中某个历史版本后,系统从基准 Snapshot 开始,加载该 Snapshot 之后直至目标 revision 的 Changeset,按顺序重放其中的 Mutation,得到一份只读的历史视图。
例如:revision 10 的 Snapshot + revision 11~15 的 Changeset = revision 15 的内容。
3. 恢复为当前版本
选中恢复此版本后,执行流程如下:
选定目标版本 → 提交恢复 Mutation → 协同确认 → 更新当前文档,产生新 revision
恢复操作本身会成为一条新的历史记录。此前的版本仍然保留。
查看版本与变更
- 在编辑器中打开历史记录,选择一个版本。
- 展开版本分组,查看其中各个 revision。选中某个 revision,即可在只读查看器中查看当时的内容和变化。
- 需要回退时,选择恢复此版本。恢复操作通过协同更新共享文档,其他参与者会收到这次改动。
一个版本分组可能合并一段时间内的多次编辑,展开后才能看到各个 revision。一条历史记录不一定对应一次按键,也不一定对应一次生成的 Snapshot。
三种颜色如何阅读
| 标记 | 含义 | 示例 |
|---|---|---|
| 🟦 蓝色:修改 | 已有内容发生变化。 | 数值、段落格式或对象属性被修改。 |
| 🟩 绿色:新增 | 这一版中加入的内容。 | 新增的行、段落、记录或画布对象。 |
| 🟥 红色:删除 | 这一版中移除的内容。 | 删掉的文字或对象在历史视图中保留标记。 |
颜色表示变更类型。替换文字时可能同时产生新增和删除。高亮范围由各产品的查看器决定。
五个产品的历史视图
下面的示例都来自同一个 Northstar 项目。示例内容为英文,时间线处于展开状态,便于将文档与每次变更背后的操作对照查看。
电子表格(Sheet)
Launch Budget 展示了预算和预测值的调整,以及行的新增与删除。借助工作表和操作时间线,可以定位每次改动影响的区域。
文档(Doc)
Product Launch Brief 涵盖发布日期、段落格式,以及为交付客户新增的内容。被删除的文字保留红色删除线,因此每个版本都保留了上下文。
演示文稿(Slide)
在 Launch Review 中,可以追溯目标指标和页面对象的变化。选中一条历史记录,更新、新增和移除的对象会直接标记在幻灯片上。
关系型表格(Relational Table)
Launch Tracker 展示了任务、负责人和状态的变化。记录和字段的变更结合表格上下文呈现,有助于说明业务数据何时发生变化、如何变化。
画布(Canvases)
Release Workspace 展示了规划卡片和对象属性。新增、删除和修改的对象在画布上原位保留标记,使一次规划调整更容易理解。
Coming soon:PDF 历史记录尚未提供。
在应用中接入
历史记录由两部分组成:Server SDK 的 History 扩展,以及 Web SDK 中各产品的历史插件。
- 服务端需要在核心协同之上接入 History Service、Endpoint 和持久化的 Database Adapter。该服务订阅 Unit 创建和已确认的 Changeset,建立历史索引,并对外提供版本和 Changeset 查询。
- 在浏览器端,需要注册通用历史能力和对应产品的 History / History UI 插件,然后连接历史接口。查看器加载选定的 revision 并展示其变更。自定义内容需要注册对应的查看器插件。
- 身份和授权由应用提供,服务端检查历史读取和恢复权限。历史版本可能包含当前文档已经删除的数据。
参见协同扩展模块,按 History 示例组装服务,再通过上面的产品指南接入界面。
历史索引是可重建的派生数据。已确认的 Changeset 仍是内容的权威来源。 持久化和保留策略由应用控制,历史面板不能替代备份。
与撤销、比较和 Worktree 的关系
| 能力 | 解决什么问题 |
|---|---|
| 撤销 / 重做 | 不需要历史服务即可撤回或重做一次编辑操作。 |
| 历史记录 | 跨会话追溯已确认的版本,查看变更并恢复共享内容。 |
| 内容比较 | 比较两份内容,供界面或 Agent 使用。只读比较不会恢复内容。 |
| Worktree | 隔离草稿中的修改,审阅后再合并到共享内容。 |
Agent 通过 Facade API 所做的修改,经协同确认后会进入同一条历史链路。应用可以将历史记录与内容比较结合,用于自动审阅和检查。
你觉得这篇文档如何?