react-native-mask-segment-canvas/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/interaction-guide.md

---
id: interaction-guide
title: 交互指南
---

# 🎮 交互指南

## 上色模式

1. 🔁 **初始轮播**：区域就绪后，每个区域的虚线轮廓按 `initRegionFlashMs`（默认 1s）依次闪烁；首次用户触摸时停止。
2. 🔍 **预览（未选择画笔）**：长按区域可显示触摸点下连通分量的虚线轮廓；点击黑色区域不显示轮廓。
3. 🎨 **上色（已选择画笔）**：点击底部颜色条中的颜色或调用 `ref.setPaintColor`（或通过 `initialPaintColor` 预设），然后点击区域上色；再次点击同一区域会覆盖颜色。
4. 💬 **无画笔点击**：不执行上色；`onPaintCallback` 触发 `kind: 'brush_required'`，携带提示信息和目标区域信息，供宿主显示 Toast/弹窗提示选择颜色。
5. ↩️ **撤销**：左下按钮或 `ref.reset()`；按上色历史逐步后退。
6. 👁️ **与原图对比**：右下按钮或 `ref.swap()`；隐藏上色层以显示原图。

## 套索模式（手动墙面分割）

当 `manualSplitWalls` 启用且套索模式激活时：

7. 🧲 **进入套索**：调用 `ref.startLasso()` 激活套索模式。套索多边形叠加层（橙色）出现。
8. 👆 **放置顶点**：点击墙面区域放置多边形顶点。顶点会自动吸附到墙面遮罩边缘/角点。
9. 🧲 **磁性套索**（当 `magneticLasso: true`）：点击之间的路径自动沿图像强边缘走（绿色路径叠加层），通过 Sobel 梯度 + Dijkstra 最短路径实现。
10. 🔒 **闭合多边形**：点击第一个顶点附近闭合多边形。闭合多边形以橙色轮廓显示。
11. ✋ **拖拽顶点**：触摸并拖拽已有顶点重新定位。顶点吸附到墙面边界/角点，或保持在墙面遮罩内部位置。
12. ✅ **结束套索**：调用 `ref.endLasso()` 将所有闭合多边形转换为可上色的 `wall-N` 子区域。
13. 🗑️ **取消套索**：调用 `ref.cancelLasso()` 丢弃所有进行中的套索多边形，不保存。
14. 🗑️ **删除套索**：调用 `ref.deleteLasso(id)` 删除之前提交的套索多边形及其关联的 `wall-N` 区域。

### 主动轮廓精炼

当 `activeContourRefine: true` 时，闭合套索多边形在 `endLasso()` 后自动精炼：

- 每个顶点沿其外法线方向采样位置
- 顶点向外扩展到最近的墙面遮罩边界边缘（气球队列力）
- Douglas-Peucker 简化去除冗余顶点
- 结果：多边形贴合真实墙面轮廓，而非原始点击位置