# React View Panel 操作文档

本文档用于说明 `react-view` 面板的核心操作流程，重点覆盖节点编辑、图层管理、映射图层、网格布局、图表配置、音视频节点与交互优化能力。

## 1. 基础结构

- 左侧：物料区 + 节点树
- 中间：画布操作区（支持拖拽、缩放、框选、对齐）
- 右侧：配置区（按分类折叠展开）
- 顶部：导航栏（预览/导入/导出/字体等）
- 操作工具栏：撤销、重做、层级设置、主题、缩放、产物名称

## 2. 节点基础操作

### 2.1 新建节点

1. 在左侧物料区拖拽物料到画布。
2. 在当前缩放比例下，系统会自动换算落点到正确逻辑坐标。
3. 空白节点（如图片/视频/音频未配置时）会显示占位，便于定位。

### 2.2 选择与多选

- 单击节点：选中
- `Shift + 单击`：增减多选
- 框选：批量选中

### 2.3 变换

- 支持拖拽、缩放、旋转
- 若节点锁定或所在图层锁定，变换会被禁用并提示

## 3. 配置区使用说明

配置区已按类别分组，支持折叠收纳。常见分组：

- 节点信息（名称、锁定等）
- 基础样式（背景、边框、圆角）
- 图表配置（基础 + JSON 高级）
- 文本配置（富文本 + 输入能力）
- 网格布局配置
- 音频配置 / 视频配置

> 说明：当节点不可编辑（节点锁定或图层锁定）时，配置区会整体置灰禁用。

## 4. 图层与映射图层

### 4.1 图层锁定

- 锁定后：
  - 该图层不可删除
  - 图层内节点不可操作（变换/层级等）

### 4.2 映射图层

- 入口：节点右键菜单「在映射图层打开」
- 特性：
  - 是源节点的映射副本，不会让源图层节点消失
  - 映射图层不可参与合并
  - 节点树和图层栏有“映射”标识
  - 支持「定位到源节点」
  - 删除源节点前会弹确认（会说明影响的映射图层数量）
  - 源节点删除后，关联映射图层会级联删除

## 5. 网格（Grid）节点

### 5.1 能力

- 可配置：行、列、间距、内边距、吸附阈值
- 普通节点靠近网格槽位可自动吸附
- 槽位有占用态显示，避免重复占位
- 节点树中网格会展示子节点层级
- 支持网格嵌套，内置循环依赖防护

### 5.2 联动

- 移动网格节点会带动子节点（支持递归）
- 改网格参数/尺寸后会自动重排子节点

## 6. 文本节点

- 配置区支持富文本内容编辑
- 支持字体、字号、粗细、颜色、对齐、行高
- 支持开关：`允许在画布内直接输入`（默认开）
- 配置区与画布内容双向同步

## 7. 图表节点

支持配置：

- 渲染模式：`Canvas / SVG`
- 标题、颜色
- X/Y 轴名称
- X/Y 轴刻度线显示与颜色
- X/Y 轴分割线显示与颜色
- axisLabel：颜色、字号、自动缩略/隐藏重叠
- tooltip：开关、触发方式、背景色、文字色、formatter
- 高级 JSON：显示当前图表完整配置并可编辑

## 8. 音频节点

### 8.1 音频来源

- 支持 URL 输入
- 支持本地上传
- 支持录音生成并播放

### 8.2 占位图标模式

可配置：

- 预设图标（喇叭/音符/耳机/声波）
- 上传占位图

当设置占位图标/占位图后：

- 节点上隐藏进度条
- 改为点击图标（或图片）播放/暂停

### 8.3 播放动效（可配置）

- 动效类型：`无动效 / 呼吸高亮 / 波纹扩散`
- 动效速度：`慢 / 中 / 快`
- 仅在“正在播放”时显示动效

### 8.4 编辑态自动暂停（可配置）

- 开关：`编辑时自动暂停媒体`
- 默认开启
- 开启后，节点被选中进入编辑态时会自动暂停，提升操作顺滑度

## 9. 视频节点

### 9.1 视频来源

- 支持 URL 输入
- 支持本地上传
- 配置区支持预览

### 9.2 画布交互优化

- 节点内使用轻量播放交互（避免原生控件抢事件）
- 播放按钮点击已做事件隔离，避免“跟手拖拽”
- 支持 `编辑时自动暂停媒体` 开关（与音频一致）

## 10. 主题与字体

- 主题支持持久化（`localStorage`）
- 默认首次为深色主题
- 字体大小支持大/中/小，并持久化
- 项目滚动条随主题变化

## 11. 常见问题排查

### Q1：节点拖不动/改不了尺寸？

- 检查节点是否锁定
- 检查所在图层是否锁定

### Q2：图层删不掉？

- 普通图层可能被浅拷贝引用
- 映射图层可独立删除（不受浅拷贝阻断）

### Q3：音频设置了 icon 但没播放？

- 检查是否已配置音频源（URL/上传/录音）
- 未配置音频时只显示 icon，不会实际播放

### Q4：播放时操作不顺畅？

- 建议开启 `编辑时自动暂停媒体`
- 使用轻量播放按钮，避免原生控件抢占拖拽事件

---

如需继续补充「快捷键说明」「导入导出格式规范」「团队使用约定」，可在本文件后续追加章节。

## 12. 产品/测试验收清单

> 建议按「基础能力 -> 复杂联动 -> 异常路径」顺序验收。

### 12.1 基础交互

- [ ] 物料可拖入画布，任意可视区域都可落点
- [ ] 缩放后新建节点落点仍准确
- [ ] 单选、多选、框选行为正常
- [ ] 撤销/重做可回放关键操作

### 12.2 锁定能力

- [ ] 节点锁定后不可拖拽/缩放/旋转/层级调整
- [ ] 图层锁定后图层内节点均不可操作
- [ ] 锁定状态在节点树与 Moveable 上有可视标识
- [ ] 不可操作时有清晰提示（Toaster）

### 12.3 配置区

- [ ] 配置项按类别分组且可折叠
- [ ] 节点/图层锁定时配置区整体置灰禁用
- [ ] 颜色项同时支持文本输入与调色盘
- [ ] 输入框聚焦无高亮边框（符合当前设计规范）

### 12.4 图表节点

- [ ] 图表标题为空时不回退到节点 id
- [ ] 基础配置包含 X/Y 轴名称、刻度线、分割线
- [ ] axisLabel 颜色/字号/自动缩略可生效
- [ ] tooltip 显示、触发、颜色、formatter 可生效
- [ ] 渲染模式切换 `Canvas/SVG` 正常
- [ ] 高级 JSON 展示当前完整配置（非空对象）

### 12.5 网格节点

- [ ] 支持行列/间距/内边距/吸附阈值配置
- [ ] 节点靠近槽位可吸附，且防止重复占位
- [ ] 节点树正确显示网格父子层级
- [ ] 网格移动可带动子节点（含递归）
- [ ] 网格参数变化会触发子节点自动重排
- [ ] 支持网格嵌套且无循环依赖

### 12.6 映射图层

- [ ] 右键「在映射图层打开」可创建映射图层
- [ ] 映射图层不影响源图层节点可见性
- [ ] 映射图层/映射节点有清晰标识
- [ ] 支持「定位到源节点」
- [ ] 删除源节点前出现影响确认弹窗
- [ ] 删除源节点后关联映射图层级联删除
- [ ] 映射图层可独立删除且不受浅拷贝阻断

### 12.7 文本节点

- [ ] 配置区富文本编辑与画布内容双向同步
- [ ] 字体/字号/粗细/颜色/对齐/行高生效
- [ ] `允许在画布内直接输入` 开关生效

### 12.8 音频节点

- [ ] 支持 URL、上传、录音三种来源
- [ ] 设置占位图标/占位图后，节点不显示进度条
- [ ] 占位模式下点击节点可播放/暂停
- [ ] 播放动效类型与速度配置可生效
- [ ] 开关 `编辑时自动暂停媒体` 可控制选中时自动暂停
- [ ] 播放按钮点击不会触发节点“跟手拖拽”

### 12.9 视频节点

- [ ] 支持 URL、上传两种来源并可预览
- [ ] 节点内可播放/暂停，且不抢占拖拽操作
- [ ] 开关 `编辑时自动暂停媒体` 可控制选中时自动暂停

### 12.10 持久化与主题

- [ ] 主题切换后刷新仍保持上次设置
- [ ] 首次进入默认深色主题
- [ ] 字体大小设置刷新后保持
- [ ] 滚动条样式随主题变化

### 12.11 异常与提示

- [ ] 图层删除被引用阻断时有明确提示
- [ ] 锁定导致操作失败时提示信息明确
- [ ] 关键删除流程采用 Dialog/AlertDialog 且无蒙层

---

## 13. 回归建议

每次改动后，至少做以下最小回归：

1. 新建 1 个图表、1 个文本、1 个网格、1 个音频、1 个视频节点；
2. 对每个节点完成一次拖拽、缩放、旋转、锁定/解锁；
3. 执行一次映射图层创建、定位源节点、删除映射图层；
4. 切换主题与字体后刷新页面确认持久化；
5. 检查撤销/重做链路是否仍稳定。
