# Open MindMap
[](https://www.npmjs.com/package/@xiangfa/mindmap)
[](https://www.npmjs.com/package/@xiangfa/mindmap)
[](https://bundlejs.com/?q=%40xiangfa%2Fmindmap%400.6.5%2Fviewer)
[](./LICENSE)
[](https://react.dev)
一个精美的 React 交互式思维导图组件。
**原生支持 AI 流式输出**，使用 Markdown 列表语法，搭配 **iOS 风格 UI**。
零依赖。基于 SVG。键盘优先。支持暗色模式。
[English](README.md) | 中文
---
## 特性
- **AI 流式输出** — 原生支持 AI 流式输出；输入 Markdown 列表，实时生成思维导图
- **内置 AI 生成** — 连接任意 OpenAI 兼容 API，通过自然语言生成思维导图；支持文本、图片和 PDF 附件上传
- **纯 SVG 渲染** — 无 Canvas、无外部布局引擎，任意缩放级别下都清晰锐利
- **iOS 风格 UI** — 毛玻璃控件、圆角设计、流畅动画，简洁精致
- **插件系统** — 7 个内置插件扩展语法（虚线、折叠、多行、标签、跨链接、LaTeX、frontmatter）；完全可扩展
- **行内格式化** — 节点内支持 **加粗**、_斜体_、`代码`、~~删除线~~、==高亮== 和 [链接](url)
- **任务状态** — `[x]` 已完成、`[ ]` 待办、`[-]` 进行中复选框
- **备注** — 通过 `>` 语法为节点附加多行备注
- **文本编辑模式** — 在可视化思维导图与纯文本 Markdown 编辑之间切换
- **全屏模式** — 将组件扩展为全屏显示
- **LaTeX 数学公式** — 渲染 `$...$` 行内公式和 `$$...$$` 块级公式（需安装 KaTeX）
- **跨链接** — 通过 `{#anchor}` / `-> {#target}` 在任意节点间绘制连线
- **轻量查看器** — 独立的只读组件（`MindMapViewer`），体积减少约 48%；通过 `@xiangfa/mindmap/viewer` 导入以获得最小打包体积
- **只读模式** — 仅显示，支持平移/缩放/选择但不可编辑；适合演示和嵌入
- **多根节点** — 在同一画布上构建多棵独立的树
- **拖拽排序** — 拖拽重新排列兄弟节点；拖拽根节点的子节点跨越中线以重新平衡两侧
- **撤销 / 重做** — 为可视化编辑、导入、拖拽排序、剪切/粘贴和程序化替换提供画布级历史
- **搜索与标签筛选** — 搜索节点、跳转匹配项，并在保留祖先上下文的同时淡化非匹配标签分支
- **键盘快捷键** — 方向键导航、Tab/Shift+Enter 添加子/兄弟节点、Enter/F2 编辑、Delete 删除、Cmd/Ctrl+Z 撤销、Cmd+C/V 复制粘贴、Shift+ 快捷键控制缩放和布局
- **Markdown 输入输出** — 输入 Markdown 列表，输出思维导图（非常适合 AI 流式输出）
- **国际化** — 自动检测浏览器语言；内置中文和英文，支持通过 props 完全自定义
- **暗色模式** — 自动检测 `prefers-color-scheme`，也可显式设置 `light` / `dark`
- **导出** — 开箱即用的 SVG、高 DPI PNG 和 Markdown 导出
- **导入** — 通过右键菜单导入对话框粘贴 JSON 或 Markdown 数据
- **右键菜单** — 右键添加根节点、导入数据、导出或更改布局
- **布局模式** — 左侧、右侧或两侧均衡布局
- **移动端优化** — 完整的触控支持，单指平移/拖拽，双指捏合缩放，以内容为中心
- **工具栏控制** — 通过 `toolbar` prop 显示/隐藏缩放、历史、搜索和标签控件
- **极小体积** — 除 React 外零运行时依赖
## 安装
```bash
# npm
npm install @xiangfa/mindmap
# pnpm
pnpm add @xiangfa/mindmap
# yarn
yarn add @xiangfa/mindmap
```
如需 LaTeX 数学公式渲染，还需安装 KaTeX（可选）：
```bash
npm install katex
```
## 快速开始
```tsx
import { MindMap } from "@xiangfa/mindmap";
import "@xiangfa/mindmap/style.css";
const data = `
我的思维导图
- 第一个主题
- 子主题 A
- 子主题 B
- 第二个主题
`;
function App() {
return ;
}
```
> **注意：** 组件会填充其父容器。请确保父容器有明确的尺寸。
## 使用方法
### 多根节点
传入数组以在同一画布上渲染多棵独立的树：
```tsx
```
### Markdown 输入
直接输入 Markdown 列表 — 非常适合流式 AI 响应：
```tsx
const markdown = `
机器学习
- 监督学习
- 分类
- 回归
- 无监督学习
应用领域
- 自然语言处理
- 计算机视觉
`;
;
```
在 Markdown 中用空行分隔不同的根节点树。
### 只读模式
仅显示思维导图而不允许编辑 — 适合演示、文档或嵌入场景：
```tsx
```
在只读模式下，用户仍可平移、缩放和选择节点，但不能创建、编辑或删除节点。右键菜单会隐藏编辑操作（新建根节点、导入），保留仅查看操作（导出、布局）。
### 轻量查看器
对于注重打包体积的只读场景（仪表盘、文档、嵌入），可使用 `MindMapViewer` — 一个独立组件，不包含编辑钩子、AI 输入、右键菜单、导出工具等，打包体积减少约 48%。
```tsx
// 通过子路径导入获得最小体积：
import { MindMapViewer } from "@xiangfa/mindmap/viewer";
import "@xiangfa/mindmap/style.css";
;
```
或从主入口导入（支持 tree-shaking）：
```tsx
import { MindMapViewer } from "@xiangfa/mindmap";
```
`MindMapViewer` 支持所有渲染功能：主题、插件、平移/缩放、折叠切换、备注提示和缩放/布局快捷键。**不**包含编辑、拖拽排序、AI 生成、右键菜单、导出或文本编辑器。
### 文本编辑器模式
传入 `MindMapTextEditor` 组件以启用内置的文本编辑模式，支持语法高亮。用户可以通过右下角的按钮在可视化思维导图与 Markdown 文本编辑器之间切换。
```tsx
import { MindMap, MindMapTextEditor } from "@xiangfa/mindmap";
;
```
文本编辑器是可选引入的，支持 tree-shaking — 只有在导入并传入该组件时才会被打包。如果省略，文本模式切换按钮将被隐藏。
### 暗色模式
```tsx
{/* 跟随系统（默认） */}
{/* 始终暗色 */}
{/* 始终亮色 */}
```
### 自定义样式
通过覆盖容器上的 CSS 自定义属性来定制颜色、字体等：
```css
/* 覆盖主题变量 */
.mindmap-container {
--mindmap-root-bg: #1a73e8;
--mindmap-canvas-bg: #f0f4f8;
--mindmap-node-text: #1a1a2e;
}
```
通过语义化 CSS 类选择器定制特定元素：
```css
/* 定制所有连线 */
.mindmap-edge {
stroke-width: 3;
}
/* 定制根节点背景 */
.mindmap-node-root .mindmap-node-bg {
fill: #6c5ce7;
}
```
通过 `data-branch-index` 定制各分支颜色：
```css
.mindmap-edge[data-branch-index="0"] {
stroke: #e74c3c;
}
.mindmap-edge[data-branch-index="1"] {
stroke: #2ecc71;
}
```
#### CSS 变量分组
| 分组 | 变量 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 画布 | `--mindmap-canvas-bg` |
| 根节点 | `--mindmap-root-bg`、`--mindmap-root-text`、`--mindmap-root-font-size`、`--mindmap-root-font-weight`、`--mindmap-root-font-family` |
| 子节点 | `--mindmap-node-text`、`--mindmap-node-font-size`、`--mindmap-node-font-weight`、`--mindmap-node-font-family` |
| 一级节点 | `--mindmap-level1-font-size`、`--mindmap-level1-font-weight` |
| 连线 | `--mindmap-edge-width` |
| 选中态 | `--mindmap-selection-stroke`、`--mindmap-selection-fill` |
| 高亮 | `--mindmap-highlight-text`、`--mindmap-highlight-bg` |
| 添加按钮 | `--mindmap-addbtn-fill`、`--mindmap-addbtn-hover`、`--mindmap-addbtn-icon` |
| 控件 | `--mindmap-controls-bg`、`--mindmap-controls-text`、`--mindmap-controls-hover` |
| 右键菜单 | `--mindmap-ctx-bg`、`--mindmap-ctx-text`、`--mindmap-ctx-hover`、`--mindmap-ctx-border`、`--mindmap-ctx-shadow` |
| 分支颜色 | `--mindmap-branch-0` 至 `--mindmap-branch-9` |
#### CSS 类选择器
| 类名 | 目标 |
| ------------------------- | ----------------- |
| `.mindmap-node-root` | 根节点分组 |
| `.mindmap-node-child` | 子节点分组 |
| `.mindmap-node-bg` | 节点背景矩形 |
| `.mindmap-node-text` | 节点文本元素 |
| `.mindmap-node-underline` | 子节点下划线 |
| `.mindmap-edge` | 连接线 |
| `.mindmap-edge-label` | 连线标签文本 |
| `.mindmap-add-btn` | 添加子节点按钮 |
| `.mindmap-fold-btn` | 折叠/展开切换按钮 |
| `.mindmap-tag` | 标签徽章 |
导出的 SVG 会嵌入一个包含已解析 CSS 值的 `