Files
Endoleap/docs/03-edit.md
T

60 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 3. 一次编辑如何成立
[上一章](02-open.md) · [目录](README.md) · [下一章](04-view.md)
## 把“改标题”翻译成命令
假设当前节点有有效 target,支持对应编辑能力。标题从“想法”改为“行动”的核心接口形态是:
```ts
engine.editor.dispatch({
type: 'element.data',
target, // 当前元素的 { id, incarnation }
patch: { title: '行动' },
});
```
这只是已取得 engine 后的命令示意。真实界面还要处理焦点、编辑租约、目标是否仍有效等问题。不要绕过命令直接修改 snapshot 中的 Map 或元素对象;它们是受保护的发布结果。
## 从命令到候选文档
[editor.ts](../src/lib/canvas-core/editor.ts) 的 `dispatch` 是同步 `transaction` 的便捷封装。事务内部先在候选文档上规划命令,得到 changes。规划会解析目标、检查宿主 policy、组件能力和字段规则;提交前还会对候选文档做整体校验。
Registry 在这里负责解释“这个组件允许什么”。一个元素存在,不等于它支持任意命令。未来版本和未知组件可以保留原始数据,但不能借此调用未安装的行为。
Change 描述实际发生的变化,OperationIntent 描述需要同步的逻辑意图,HistoryEntry 则组织用户可撤销的工作单元。它们有关联,却不是同一个对象。
## 为什么两个命令可以一起成功或一起失败
例如一个 counter 节点同时移动位置并把 count 改为负数。第一条命令可以在候选文档中成立,第二条违反 schema。事务最终拒绝时,候选文档被丢弃,原文档、历史、操作记录和通知均不应留下第一条命令的结果。
完整例子在 [consumer.mjs](../headless/consumer.mjs):找到标有“非法事务”的部分,再与后面的合法事务比较。合法的移动与计数更新被组织成一个历史单元。
事务回调必须同步。异步读取和资源准备先在事务外完成,再带着仍需重新验证的目标进入事务。`await` 期间世界可能变化,不能持有一个可在稍后继续写的事务草稿。
## 发布边界里还有 runtime
事务成功后进入 `publish`,构造历史与操作等候选状态。engine 创建 Editor 时注入 `reduceRuntime`,将新操作合入 ledger,并整合相关资源任务;`prepareRuntime` 再检查所有权、加载和资源保留等规则。
这些准备在最终 state 赋值之前完成,因此“文档已改但待同步操作没有入账”不应成为一次成功提交的状态。准备钩子不做网络 I/O;如果它们偷偷产生外部写入,丢弃候选根也无法撤销外部副作用。
订阅者随后观察已发布状态,更新页面或调度后续工作。监听器发生异常不能把已经提交的文档倒回去。
## 撤销为什么不是恢复整个旧快照
撤销根据历史变化与当前状态执行校验,再发布补偿意图。它必须保留期间到来的有效服务端资源确认等运行事实。如果只是把整个状态替换成编辑前的快照,这些事实会丢失。
同字段冲突时撤销可能拒绝,并保持历史栈不动。删除后撤销恢复元素会产生新的 incarnation,因此此前捕获的 target 继续失效。一次无实际变化的提交可以返回 applied,但不产生新的 operation;applied 不代表必然发生写入。
## 跟踪任务
先跟踪 `dispatch → transaction → plan → publish`,再到 [engine.ts](../src/lib/canvas-runtime/engine.ts) 找 `createEditor` 的 `reduceRuntime` 和 `prepareRuntime`。标出候选状态在哪里变成发布状态。
在 [core.test.mjs](../tests/headless/core.test.mjs) 阅读标题含 `rejected second command`、`same-field conflict`、`async transactions` 的测试。分别写出它们保护的事实。
## 自检
**`dispatch()` 返回 applied,是否意味着服务器已保存?**
不是。它说明本地命令已成功处理;还需区分有无实际变化、本地可靠持久化是否完成,以及操作是否收到并协调了服务器回执。下一章看页面为什么能先响应,第 5 章再看后续可靠性。