mnote/design/06-mindmap/reference/6-mindmap-leptos-adapter-reference-notes-v1.md

# 6 [reference] Mindmap leptos adapter reference notes v1

> 日期：2026-05-10
>
> 当前状态：`reference`。本文是 adapter/reference 审计笔记，不作为当前执行 checklist；mindmap 实施状态以 `6-mindmap-phase6-leptos-ui-shell-reuse-checklist-v1` 和 `done/6-mindmap-phase6-kmind-parity-detail-checklist-v1.md` 为准。
>
> 目的：记录 `lx-doc/mind-map` 与 KMind 插件审计结果，为 Phase 6 `leptos-mindmap` 的 simple-mind-map bridge、command bridge 和第一阶段 UI 复刻定界。

## 1. 参考入口

- `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/Edit.vue`
  - 注册 `simple-mind-map` 插件。
  - 初始化 `new MindMap({ el, data, layout, theme, themeConfig, viewData, config })`。
  - 承接 `execCommand`、关联线、图片上传、富文本、滚动条等 runtime 行为。
- `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/ToolbarNodeBtnList.vue`
  - 提供节点编辑工具栏命令和禁用状态参考。
- `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/SidebarTrigger.vue`
  - 提供右侧栏触发器参考。
- `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/config/zh.js`
  - `sidebarTriggerList` 定义 `nodeStyle/baseStyle/theme/structure/outline/shortcutKey`。
- `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/NavigatorToolbar.vue`
  - 提供底部导航工具参考。
- `design/05-editor-mainline/reference-code/kmind-plugin/README.md`
  - 提供 KMind 的思源耦合能力与延期边界参考。

## 2. 本轮需要注册的插件

第一阶段必须注册：

- `Drag`：画布拖拽、节点拖拽编辑的基础能力。
- `KeyboardNavigation`：方向键、基础键盘导航。
- `Export`：导出入口的基础能力，先保留 UI 与 runtime 能力，不把导出结果当 kernel truth。
- `Select`：框选、多选与 active node 状态。
- `AssociativeLine`：关联线渲染与创建入口。
- `Search`：底部搜索入口需要。
- `OuterFrame`：外框按钮与已有 KMind/lx-doc 视觉能力对齐。

第一阶段建议按能力开关注册：

- `RichText`：仅在节点富文本开启时加载；富文本 HTML 进入 `compatPayload`，同时保留纯文本到 kernel node text。
- `Scrollbar`：仅在配置开启时加载，避免小画布重复滚动 UI。
- `MiniMap`：底部按钮可以延期显示，但 bridge 应保留插件注册能力。
- `Painter`：格式刷属于 toolbar 第一阶段按钮，样式变更先走 `compatPayload.patch`。
- `Formula`：公式先作为节点扩展字段进入 `compatPayload`。

第一阶段不作为必须注册：

- `ExportPDF` / `ExportXMind`：导出格式能力可保留在独立页或后续任务，不阻塞 block 内编辑。
- `Watermark`：不属于当前 mnote 主体验。
- `TouchEvent`：移动端可用性后续补齐。
- `RainbowLines` / `Demonstrate` / `HandDrawnLikeStyle` / `Notation`：作为高级视觉或演示能力延期。
- `NodeImgAdjust`：图片字段先兼容保存，图片尺寸调整后续再语义化。

## 3. Toolbar 到 kernel command 的映射

直接发 kernel command：

- `INSERT_CHILD_NODE` -> `mindmap.node.insert_child`
- `INSERT_NODE` -> `mindmap.node.insert_sibling_after`
- `REMOVE_NODE` -> `mindmap.node.delete`
- 节点文本提交 -> `mindmap.node.update_text`
- 节点拖拽换父或重排 -> `mindmap.node.move`
- 结构切换 -> `mindmap.layout.set`
- 主题切换 -> `mindmap.theme.set`
- 缩放、平移、只读状态以外的 view 变化 -> `mindmap.view.patch`

需要 bridge 或 diff 二次确认：

- `BACK` / `FORWARD`：第一阶段作为 runtime history 操作；后续若 kernel history 接管，再提升为 kernel undo/redo。
- `ADD_GENERALIZATION`：映射到 `mindmap.summary.set`，当前 Rust DTO 最小集未完全覆盖时先进入 `compatPayload.patch` 并记录字段路径。
- `createAssociativeLine`：映射到 `mindmap.associative_line.upsert`，当前 Rust DTO 最小集未完全覆盖时先进入 `compatPayload.patch`。
- `ADD_OUTER_FRAME`：第一阶段进入 `compatPayload.patch`，后续提升为 outer frame kernel 语义。

第一阶段作为 compat 字段处理：

- 图片、图标、标签、超链接、备注、公式、附件、标记、格式刷产生的节点样式。
- 这些入口可以出现在 UI 中，但保存路径必须经过 command bridge；不可直接把整棵 runtime data 保存为 canonical truth。

## 4. 右侧栏第一阶段保留项

第一阶段保留：

- `nodeStyle`：节点样式。可编辑项先进入节点 `compatPayload`，基础文本仍回写 kernel。
- `baseStyle`：导图样式。概要、关联线、间距等暂未语义化字段进入 `compatPayload`。
- `theme`：主题切换，能识别的主题名走 `mindmap.theme.set`。
- `structure`：结构切换，走 `mindmap.layout.set`。
- `outline`：大纲只作为 projection 派生视图，不创建第二套树真相。

第一阶段不放入右侧栏：

- `shortcutKey`：快捷键说明可以后续做文档或设置面板，不阻塞编辑器主链。
- KMind 全局配置、主题设计器、主题分享：后续独立配置任务处理。

## 5. 底部工具第一阶段保留项

第一阶段保留：

- 节点数 / 字数：从 adapter projection 或 runtime 派生，只读展示。
- 回根节点：调用 `mindMap.renderer.setRootNodeCenter()`，同时可记录 view patch。
- 搜索：调用 `Search` 插件或事件入口。
- 缩放百分比：监听 `scale`，通过 `view_data_change` / `mindmap.view.patch` 保存必要 view state。
- 全屏或只读：block 内优先保留只读切换；独立页可提供全屏。

第一阶段可延期：

- 鼠标行为高级配置。
- MiniMap 展示按钮。
- 暗色主题切换。
- 源码编辑。
- 演示模式。
- 多语言切换和帮助链接。

## 6. 必须进入 compatPayload 的字段

节点级字段：

- `image`、`imageTitle`、`imageSize`
- `icon`
- `tag`
- `hyperlink`、`hyperlinkTitle`
- `note`
- `richText`
- `generalization` 中尚未进入 kernel summary DTO 的私有样式字段
- `formula`
- `attachment`
- `notation`
- 节点自定义样式、内外边距、背景、字体、边框、图片调整状态
- `customLeft`、`customTop` 等自由布局坐标

导图级字段：

- `theme.config` 中无法映射到 kernel theme 的细项。
- `config` 中 runtime 私有行为配置，如鼠标行为、粘贴拆分、图片上传默认值。
- `view` 中无法映射到稳定 view DTO 的细项。
- `outerFrame`、高级关联线样式、概要样式。
- 插件私有状态，如 `MiniMap`、`Painter`、`Demonstrate`、`Notation`。

保存约束：

- `compatPayload` 只能承接暂未语义化字段。
- 每次 `compatPayload.patch` 必须记录字段路径、来源事件和 kernel revision。
- 不允许把 `root` 整棵 runtime data 作为唯一成功保存结果。

## 7. KMind 专有能力延期

延期到 Phase 6 之后：

- 多根节点。
- MOC 模式。
- 文档树导图。
- 思源块拖拽、渲染、悬浮预览。
- 节点镜像块与导图镜像块。
- 思源 PDF 标注跳转与移除 PDF 关联。
- 思源全局搜索对接。
- 子文档快捷打开位置。
- KMind 全局配置、自动禅模式、默认主题与默认结构。
- 主题设计器、主题分享。
- 历史版本、固定历史版本、自动历史清理。
- Freemind / XMind 全量导入导出。
- 右键菜单中的思源专有导出、复制镜像块、复制节点为图片等高级项。

这些能力可以影响长期设计，但不能改变 Phase 6 的主合同：`simple-mind-map` 是 editor adapter，Rust kernel projection / command 才是事实源。

## 8. 历史自研 React UI 壳复用清单

> 2026-05-11 复核：历史 React UI 壳比 `/mnt/Data1T/mnote-rust/components/editor/blocks` 的简化宿主完整得多。下一阶段迁移应优先抽取历史 React 组件族的配置和 action 语义，不应继续在 NodeView 内手写按钮。
>
> 2026-05-11 执行记录：上述能力清单已转为 `mindmap-ui-schema.ts` / `mindmap-action-map.ts` / Leptos/Rust shell 的第一阶段输入；旧 React 组件族已补 legacy/reference/compat 注释，默认 3000 文档页不运行旧 React mindmap 主链。

### 8.1 Toolbar

| 分组 / action | 旧来源 | 旧 runtime 调用或意图 | active node | 第一阶段 |
|---|---|---|---|---|
| 工具栏元信息 | `wolai-frontend/src/components/editor/blocks/mindmapToolbarConfig.ts`：`NodeToolbarKey`、`FileToolbarKey`、`nodeToolbarOrder`、`fileToolbarOrder`、`nodeToolbarMeta`、`fileToolbarMeta` | 定义按钮 key、label、iconClass 和顺序 | 视 action | schema-only |
| toolbar UI 分组 | `MindmapToolbar.tsx`：`nodeHandlers`、`fileHandlers` | 左侧节点操作、右侧文件/导入/导出；能力由 props 注入 | 视 action | must |
| undo / redo | `MindmapBlock.tsx`：`handleUndo`、`handleRedo` | `mindmap.execCommand("BACK" / "FORWARD")` | 否 | must |
| 同级 / 子节点 | `MindmapBlock.tsx`：`handleSibling`、`handleChild` | `SET_NODE_ACTIVE` 后 `INSERT_NODE` / `INSERT_CHILD_NODE`；无 active 时 `ensureActiveBefore` 选 root | 是 | must |
| 删除 / 概要 / 关联线 / 外框 | `MindmapBlock.tsx`：`handleDelete`、`handleSummary`、`handleAssociativeLine`、`handleOuterFrame` | `REMOVE_NODE`、`ADD_GENERALIZATION`、`ADD_ASSOCIATIVE_LINE`、`ADD_OUTER_FRAME` | 是 | must |
| 图片 | `MindmapBlock.tsx`：`handleImage`、`handleImageConfirm` | 输入/上传图片后 `SET_NODE_IMAGE` + `SET_NODE_STYLES imgPlacement` | 是 | must |
| 超链接 / 标签 / 备注 / 附件 | `MindmapBlock.tsx`：`handleLink`、`handleTag`、`handleNoteConfirm`、`handleAttachment` | `SET_NODE_HYPERLINK`、`SET_NODE_TAG`、`SET_NODE_NOTE`、`SET_NODE_ATTACHMENT` | 是 | must |
| 图标 / 公式 | `MindmapBlock.tsx`：`handleIcon`、`handleFormula` | 打开 sidebar `icons` / `formula` | 是 | schema-only / defer |
| 格式刷 | `MindmapBlock.tsx`：`handlePainter` | `mindmap.painter.startPainter()` | 否，依赖 Painter 插件 | defer |
| 导入 / 新建 / 本地恢复 / 导出 / 删除导图 | `MindmapBlock.tsx`：`handleImport` 到 `handleDeleteMindmap` | `.json/.smm/.xmind/.mmap/.md` 导入；`setData`、`clearHistory`、`persistData`；导出 JSON/PNG/SVG/PDF/MD/TXT/XMind；删除走 `/api/mindmap/{docId}/{mindmapId}` | 否 | must |

### 8.2 Sidebar

| panel | 旧来源 | 旧 runtime 调用或意图 | active node | 第一阶段 |
|---|---|---|---|---|
| trigger 配置 | `mindmapSidebarConfig.ts`：`SidebarPanel`、`sidebarTriggers` | `style/base/theme/structure/outline/settings/icons/formula/note/ai` | 视 panel | schema-only |
| 触发条 UI | `MindmapSidebarTrigger.tsx`：`MindmapSidebarTrigger` | 右侧竖条，`onSelect(isActive ? null : target)` | 否 | must |
| panel 路由 | `MindmapSidebar.tsx`：`MindmapSidebar` switch | `activeTab` 分发到各 panel | 视 panel | must |
| 节点样式 | `MindmapSidebar.tsx`：`StylePanel` | `node.getStyle(prop,false)` 读取，`node.setStyle(prop,value)` 写入文字、边框、填充、连线样式 | 是 | must |
| 基础样式 | `MindmapSidebar.tsx`：`BaseStylePanel` | `mindmap.getThemeConfig` / `mindmap.setThemeConfig` | 否 | must |
| 主题 | `MindmapSidebar.tsx`：`ThemePanel` | `mindmap.setTheme(theme)` | 否 | must |
| 结构 | `MindmapSidebar.tsx`：`StructurePanel` | `mindmap.setLayout(layout)` | 否 | must |
| 图标/贴纸 | `MindmapSidebar.tsx`：`IconPanel` | 动态加载 simple-mind-map icons；`node.setIcon`、`node.setImage` | 是 | must |
| 大纲 | `MindmapSidebar.tsx`：`OutlinePanel` | 从 `mindmap.renderer.renderTree._node` 遍历；点击后设置 active 并 `setRootNodeCenter` | 否 | must |
| 设置 | `MindmapSidebar.tsx`：`SettingsPanel` | `mindmap.updateConfig`、`mindmap.reRender`、`watermark.updateWatermark` | 否 | schema-only |
| 备注 | `MindmapSidebar.tsx`：`NotePanel` | 读取 active `note`，保存/清除走 `SET_NODE_NOTE` | 是 | must |
| 公式 / AI | `FormulaPanel`、`MindmapAiAgentPanel` | `INSERT_FORMULA` 或 AI panel | 是 / 部分 | defer |

### 8.3 Navigator / MiniMap / Count

| 能力 | 旧来源 | 旧 runtime 调用或意图 | active node | 第一阶段 |
|---|---|---|---|---|
| 宿主挂载 | `MindmapBlock.tsx` 全屏和内嵌 stage | 同时挂 `MindmapNavigator`、`MindmapCount`、`MindmapMiniMap`、`MindmapContextMenu` | 否 | must |
| 缩放 / 居中 / 只读 / 全屏 / 小地图按钮 | `MindmapNavigator.tsx`：`MindmapNavigator` | `view.enlarge`、`view.narrow`、`view.setScale`、`renderer.setRootNodeCenter`、`setMode("readonly"/"edit")`、`onToggleMiniMap`、`toggleFullscreen` | 否 | must |
| MiniMap | `MindmapMiniMap.tsx`：`MindmapMiniMap` | `mindmap.miniMap.calculationMiniMap`；监听 `data_change/view_data_change/node_tree_render_end/mini_map_view_box_position_change` | 否 | must |
| Count | `MindmapCount.tsx`：`MindmapCount` | `mindmap.getData()` + `data_change`，递归统计节点数和去 HTML 文本长度 | 否 | must |

### 8.4 Context Menu

| action / 组 | 旧来源 | 旧 runtime 调用或意图 | active node | 第一阶段 |
|---|---|---|---|---|
| 菜单项配置 | `MindmapContextMenu.tsx`：`NODE_MENU_ITEMS` | 插入、移动、展开、删除、复制剪切粘贴、移除属性、导出节点、AI 续写 | 是 | schema-only |
| 禁用规则 | `MindmapContextMenu.tsx`：`isItemDisabled` | root/generalization 禁用部分插入、复制剪切、移动；首尾节点禁用上移/下移 | 是 | must |
| 捕获右键目标 | `MindmapContextMenu.tsx` contextmenu listener | 监听 `mindmap-canvas`，目标取 `renderer.activeNodeList[0] ?? lastActiveNodeList[0]` | 是 | must |
| 插入/移动/删除等默认命令 | `MindmapContextMenu.tsx`：`executeCommand` default | 多数 action 直接 `mindmap.execCommand(key)` | 是 | must |
| 复制/剪切/粘贴 | `MindmapContextMenu.tsx` | `mindmap.renderer.copy/cut/paste` | 是 | must |
| 移除超链接/备注 | `MindmapContextMenu.tsx` | `targetNode.setHyperlink("", "")`、`targetNode.setNote("")` | 是 | must |
| 展开/收起下级 | `MindmapContextMenu.tsx` | `UNEXPAND_ALL`、`EXPAND_ALL` | 是 | must |
| 导出当前节点 PNG / AI 续写 | `MindmapContextMenu.tsx` | `doExport.export("png", ..., targetNode)`；`mindmap-ai-continue` custom event | 是 | defer |

`/mnt/Data1T/mnote-rust/components/editor/blocks` 只保留基础 toolbar、theme/structure/view sidebar 和简化 runtime 宿主，可作为 adapter 最小结构参考，但不能替代当前仓旧 React UI 壳的完整能力清单。