Genarrative/docs/【UI编辑器】撤销重做规范-2026-09-03.md

UI 编辑器撤销与重做规范

目标

UI 编辑器支持撤销最近一次或多次作品编辑，并支持重做被撤销的编辑，降低误操作返工成本，同时保持现有保存、AI 工作流和资产文件行为不变。

适用范围

撤销历史属于当前 UI 编辑会话，历史只保存可序列化的编辑器 State 快照，不保存页面临时状态。

纳入历史的操作：

• 设计图名称、描述、角色和从属关系修改；
• 设计图、精灵、字体资源的新增、删除和元数据修改；
• 节点新增、删除、移动、Transform、Layout、元数据、子节点显示模式修改；
• 组件新增、删除、排序和字段修改；
• AI suggest、recognize、merge，以及批量导入、批量删除等批量 State 修改，整次成功调用作为一条记录；
• bind 按后端批次逐次提交，每个成功 batch 作为一条独立记录，便于逐批撤销；
• 节点拖动或缩放，按一次按下到松开的连续操作作为一条记录。

不纳入历史的操作：

• 选择项、隐藏节点、工作流步骤、面板展开状态和画布视口等 UI 临时状态；
• 打开/切换项目、服务端重新加载和清空编辑器；这些操作替换 State 后重置历史；
• 保存、自动保存、生成代码、发布请求本身；撤销只改变本地 State，后续保存才同步远端；
• 素材上传、AI 生成等已发生的外部副作用；若副作用同时落地了本地 State，只撤销本地 State 变化；
• no-op、锁定、校验失败或目标不存在的操作。

导入资源被撤销时只回退编辑器 State 中的资源记录和引用，不删除已经写入磁盘的资产文件；重做恢复原资源 ID 与文件引用。

历史模型

• 栈按会话全局维护，最多保留最近 100 条事务；超限丢弃最旧记录。
• 每条记录保存 before 与 after 的完整结构化 State 快照，快照不复制二进制文件内容。
• 提交前后快照相同则不产生记录。
• 撤销将当前 State 恢复为记录的 before，并把记录移入 redo 栈；重做恢复 after。
• 撤销后发生新的有效编辑时清空 redo 栈。
• 撤销/重做恢复 State 时不得再次写入历史。

事务边界

• 普通字段、按钮和列表操作一次成功调用对应一条记录。
• 节点拖动/缩放期间只更新预览层临时变换；松开时提交最终变换并生成一条记录。取消、卸载、切换资源、未越过阈值或无变化不提交。
• 每次有效 commit 或 replaceState 都直接生成一条记录；bind 的每个成功 batch 独立提交。失败 batch 不产生记录，已完成的前序 batch 保留。
• 颜色选择器、九宫格边界拖动等连续控件在交互期间使用本地 draft 预览，释放或确认时一次提交。

用户入口

• 桌面端页面工具栏提供撤销和重做按钮。
• 非文本编辑目标聚焦编辑器时支持 Cmd/Ctrl+Z 撤销、Cmd/Ctrl+Shift+Z 和 Ctrl+Y 重做。
• input、textarea、select、contenteditable 等文本编辑控件交给浏览器原生行为，不拦截文本撤销；按钮/链接等非文本控件仍允许编辑器撤销/重做快捷键生效。
• UI Editor 页面内选中节点后，支持不带修饰键的 Delete 删除节点及其子节点；快捷键复用 Inspector、树面板和右键菜单共用的 deleteNode 命令，因此沿用根节点/锁定禁删、单条历史记录、dirty 标记和后续保存语义。
• Delete / Backspace 在 input、textarea、select、contenteditable、按钮和链接等交互控件聚焦时交给浏览器原生行为；无选中、根节点、锁定或目标不存在时不执行删除。长按重复事件不重复删除，成功处理后阻止默认行为和事件冒泡。
• Delete / Backspace 在打开的对话框（role="dialog" 或 aria-modal="true"）内聚焦时交给对话框处理，不删除对话框背后的节点。
• Cmd/Ctrl+Z、Cmd/Ctrl+Shift+Z 和 Ctrl+Y 在打开的对话框（role="dialog" 或 aria-modal="true"）内聚焦时暂停编辑器级撤销/重做，由对话框或浏览器原生行为处理。
• 无可撤销或重做记录时按钮禁用，并提供可访问名称。

脏状态与选择

撤销和重做恢复的 State 继续参与现有 dirty 判定、保存和后端持久化。历史快照不包含当前设计图、节点选择、隐藏集合或视口；恢复后若当前选择已不存在，页面清理无效选择并保持安全空态。

删除节点后，若当前选中节点是被删除节点或其任意后代，页面将选区清空为 null；删除成功不强制抢占焦点。该选择清理属于 UI 临时状态，不写入撤销历史。

验收标准

1. 单次字段编辑可撤销和重做。
2. 连续多次编辑按逆序撤销。
3. 节点拖动/缩放一次手势只产生一条记录，取消和零变化不产生记录。
4. AI suggest/recognize/merge 一次调用只产生一条记录；bind 每个成功 batch 产生一条记录，失败不产生该 batch 记录。
5. 撤销后新编辑清空 redo。
6. 加载/切换/清空重置历史；保存/自动保存不清空历史。
7. 撤销/重做资源导入不删除资产文件，并恢复原资源引用。
8. 工具栏按钮、禁用态和桌面快捷键可用，文本控件保留原生撤销。
9. no-op、锁定、校验失败和不存在目标不进入历史。
10. 颜色选择器和九宫格边界拖动不会按每个 pointer move 写入 State。
11. Delete / Backspace 仅在非交互控件聚焦且存在可删除选中节点时生效；删除整棵子树、可撤销、长按只处理一次，并清理被删除子树内的无效选区。