docs: specify esc hide preview controls

2026-07-04 17:21:48 +08:00
parent 92fa48bb01
commit 0dea119a4e
2 changed files with 62 additions and 0 deletions
@@ -102,6 +102,33 @@ Scene 坐标是 `QGraphicsScene` 中的坐标。
 - 选中框和控制点仅用于交互，不参与最终导出。
 - 操作提示仅显示在 UI 中，不参与最终导出。

+### 5.1 预览控制层显隐
+
+预览区的印花选中框、缩放控制点、旋转连接线和旋转控制点属于交互控制层。该控制层只帮助用户识别和操作当前印花，不属于图片内容。
+
+按键行为：
+
+- 当预览区拥有键盘焦点时，按 `Esc` 应隐藏当前印花的交互控制层。
+- `Esc` 只隐藏印花选中框、缩放控制点、旋转连接线和旋转控制点，不隐藏印花图片本身。
+- `Esc` 不执行撤销，不回滚当前拖动、缩放或旋转结果，不修改 `TransformState`。
+- 如果焦点在参数输入框、文件列表或其他控件中，预览区可以不响应该次 `Esc`。
+
+焦点规则：
+
+- `QGraphicsView` 应允许获得键盘焦点。
+- 用户点击预览区时，预览区应获得焦点，以便后续 `Esc` 能被画布接收。
+
+恢复规则：
+
+- 控制层被隐藏后，用户再次点击预览区中的印花图片，应恢复控制层，并继续沿用原有拖动逻辑。
+- 控制层隐藏期间，隐藏的缩放控制点和旋转控制点不需要响应命中测试；恢复后原有缩放、旋转行为保持不变。
+- 重新加载印花图片或创建新的印花图层时，控制层默认显示。
+
+一致性规则：
+
+- 控制层显隐状态不参与模板保存、队列项保存、单张导出或批量导出。
+- 最终导出仍只读取 `TransformState` 和原始图片，不读取控制层显隐状态。
+
 ## 6. 状态模型

 印花变换状态使用统一模型表示：
@@ -567,6 +594,9 @@ RGB 颜色距离
 - 预览缩放到 50% 或 200% 后，拖动仍能得到正确原图坐标。
 - 参数面板输入后预览同步。
 - 预览拖动后参数面板同步。
+- 点击预览区后按 `Esc`，印花选中框、缩放控制点和旋转控制点隐藏，但印花仍可见。
+- 控制层隐藏后再次点击印花，控制层恢复，拖动、缩放、旋转仍按原有规则工作。
+- 控制层显隐不改变 `TransformState`，也不影响导出结果。
 - 白色衣服配浅色印花时能标记为低对比或不明显。
 - 深色衣服配深色印花时能标记为低对比或不明显。
 - 透明 PNG 的透明区域不参与印花主色判断。