docs: add guided developer tutorial and separate local research
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
# 4. 拖动节点与画面更新
|
||||
|
||||
[上一章](03-edit.md) · [目录](README.md) · [下一章](05-sync.md)
|
||||
|
||||
## 文档坐标不是屏幕坐标
|
||||
|
||||
节点 geometry 属于 owner canvas 的局部空间。嵌套 canvas 带来祖先变换,视口又有平移与缩放。一个鼠标位置必须经过相应转换,才能成为正确的文档几何。
|
||||
|
||||
因此问题“拖完为什么跳动”至少可能来自三处:坐标转换不一致、临时预览与提交几何不一致、旧目标回调迟到。直接调整 React Flow 节点数组,可能暂时改变画面,却没有修复业务文档。
|
||||
|
||||
## 手势先预览,结束才提交
|
||||
|
||||
拖动开始时,sessions 为有效 target 建立手势;移动过程更新临时几何,投影读取有效几何来显示位置;结束时才把最终结果提交到 Editor。取消时释放预览,恢复基于已提交文档的显示。
|
||||
|
||||
这样连续 pointermove 无需每次都生成历史和网络写入。一段有效拖动可成为一个历史单元。取消只处理自己的手势,不能把这段时间并行发生的资源 ACK 或其他有效状态也撤销。
|
||||
|
||||
当前约束下,一个项目同时最多一个写几何的手势。视图 detach 或目标失效会取消对应手势;组件里的编辑租约还保护旧事件处理器,避免它在新的交互开始后提交旧目标。
|
||||
|
||||
## 从事实到可画的数据
|
||||
|
||||
[HeadlessGraphCanvas](../src/components/canvas/headless-graph-canvas.tsx) 同时消费 engine 根和 sessions。场景投影结合文档、当前视图、Registry、renderer 目录及查询,得到 React Flow 使用的节点、边和相关呈现数据。
|
||||
|
||||
投影是派生结果。元素的 owner、业务 data 和历史仍以模型为准;选择与临时预览来自会话。投影缓存与索引是为了减少重复工作,不应成为另一份可以独立编辑的业务文档。
|
||||
|
||||
[canvas-renderers.tsx](../src/components/canvas/canvas-renderers.tsx) 把 renderer 描述映射到具体 React 组件。Registry 回答“数据是什么、允许做什么”,renderer 回答“怎样显示”。只添加一个 React 节点组件,不足以完成可编辑的新类型。
|
||||
|
||||
## 更新如何到达 React
|
||||
|
||||
Editor 提交订阅先推进场景索引,再通知显示。代码对用户字段修改、undo/redo 等采用及时通知,避免受控输入落后;批量创建和后台变化允许合并到呈现帧。sessions 也有自己的通知节奏。
|
||||
|
||||
注意两种时间:文档已经提交的时间,与 React 执行下一次呈现的时间。逐帧合并通知不会把真实提交推迟到下一帧,也不能据此认为同帧发生的业务操作被合成一次事务。
|
||||
|
||||
## 跟踪任务
|
||||
|
||||
在主画布组件定位 `sceneCache`、Editor 的 `subscribe`、`createSessionFrameSource`、`sceneCache.project`,再找 `beginTransform`。画出“pointer → sessions → 投影 → React Flow”和“提交 → Editor → 投影更新”两条路径。
|
||||
|
||||
然后阅读 [consumer.mjs](../headless/consumer.mjs) 的手势取消断言:有效几何变了,但取消后文档坐标不变,请求数也不增加。它在没有 DOM 的情况下展示了业务规则。
|
||||
|
||||
## 自检
|
||||
|
||||
**视口缩放是否应改写每个节点的 geometry?**
|
||||
|
||||
不应该。视口是视图状态,模型坐标保持其业务空间含义。需要坐标转换的是输入、投影和命中过程。混淆两者会让嵌套和多视图行为难以保持一致。
|
||||
Reference in New Issue
Block a user