轻松在网页中集成专业思维导图功能 - Mind Elixir

在信息爆炸的时代，我们每天都要处理大量复杂的信息和想法。传统的线性笔记往往难以展现思维的跳跃性和关联性，而思维导图作为一种半自动档的笔记工具，能够帮助我们更好地整理思路、梳理知识结构、激发创意灵感，同时操作又比白板、画图软件的操作更便利。

无论是构建知识管理平台、在线教育网站，还是协作工具，集成思维导图功能都能显著提升用户体验，让复杂信息的展示和交互变得更加直观高效。

如果你想在自己的 Web 项目中集成思维导图功能，借助 Mind Elixir，最快只需几行代码就能在你的网站中添加专业级的思维导图功能。比如在个人博客中，你可以用思维导图来展示文章的知识结构、制作交互式的学习笔记，这样的功能不仅能让内容更加生动有趣，还能显著提升博客的专业度。

开源的 JavaScript 思维导图内核 Mind Elixir，拥有以下核心特性：

• 流畅的用户体验 交互顺滑、反馈自然，支持移动端。
• 轻量且高性能 小体积，快速加载与渲染，确保复杂图形下依然保持高帧率。
• 框架无关 无论是 React、Vue、Svelte，还是原生项目，都可轻松集成或独立运行。
• 插件式架构 灵活的插件系统，支持官方扩展或自定义插件，自由组合功能模块。
• 支持导出 PNG / HTML 将思维导图导出为图片或 HTML 页面，方便分享与嵌入。
• 节点摘要 / 节点连接 支持节点摘要、连接线、标签等多种节点样式，满足不同需求。
• 支持撤销 / 重做 完整的操作历史栈，任何修改都可快速回退或重做，放心操作。
• 高效快捷键支持 丰富的键盘快捷方式，提升专业用户的操作效率。
• CSS 变量样式自定义 通过 CSS 变量轻松控制节点样式和整体主题，实现高度定制化美观布局。

下面简单介绍一下怎么快速在你的项目中集成 Mind Elixir 吧！🤗

超简易接入

安装依赖：

npm i mind-elixir -S

引入 Mind Elixir：

import MindElixir from 'mind-elixir'
import 'mind-elixir/style' // 5.0 后的版本需要主动引入样式

当然你也可以直接用 script 引入：

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/mind-elixir/dist/MindElixir.js"></script>

在初始化前，我们还需要调整一下你的挂载目标元素样式。准确来说是需要给它一个明确的宽高，尤其注意高度哦。被 CSS 折磨过的前端朋友都知道，高度 100% 是一个比较难驾驭的设定。下面就直接以 500px 高的 div 为例。

<div id="map"></div>
<style>
  #map {
    height: 500px;
    width: 100%;
  }
</style>

接着是正式初始化，如果不考虑其他初始化选项，只需要传入挂载元素即可！

import MindElixir from 'mind-elixir'
import 'mind-elixir/style'

let options = {
  el: '#map', // or HTMLDivElement
}

let mei = new MindElixir(options)
const data = MindElixir.new('new topic')
mei.init(data)

到这里就已经完成最基础的接入啦！

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/vEOqWjE

事件监听

在你的项目里用上思维导图之后，最常见的需求便是监听事件了，你需要监听各种节点操作，然后对用户操作做出响应。例如用户新建了一个节点，你需要及时把它保存起来。

Mind Elixir 使用 bus 派发事件，这个词来源于“总线”这个概念，所有事件都会由这个“总线”派发。使用上跟浏览器的 addEventListener 类似，只要你能拿到 bus，你就可以在任何地方监听事件。

截止到最新版 Mind Elixir 5.0，有以下事件：

type EventMap = {
  operation: (info: Operation) => void
  selectNode: (nodeObj: NodeObj, e?: MouseEvent) => void
  selectNewNode: (nodeObj: NodeObj) => void
  selectNodes: (nodeObj: NodeObj[]) => void
  unselectNodes: (nodeObj: NodeObj[]) => void
  expandNode: (nodeObj: NodeObj) => void
  linkDiv: () => void
  scale: (scale: number) => void
  move: (data: { dx: number; dy: number }) => void
  updateArrowDelta: (arrow: Arrow) => void
  showContextMenu: (e: MouseEvent) => void
}

其中大部分节点操作事件都被归到 operation 事件中，Talk is cheap！在项目中加上然后再操作一下节点就很好懂了：

mei.bus.addListener('operation', (operation) => {
  console.log(operation)
})

有时候监听事件还不够，如果你需要确保数据插入到数据库之后，再让它显示出来，那就要用到操作拦截了。在 options 中加入 before 选项，这是一个对象，key 为你需要拦截的操作，如果你需要拦截 addChild 操作，可以这样写：

let mei = new MindElixir({
  // ...
  before: {
    async addChild(el, obj) {
      try {
        await saveToDatabase(obj)
        return true
      } catch (error) {
        console.error('Error adding child:', error)
        return false
      }
    },
  },
})

这样在 saveToDatabase() 运行成功之后才会真正添加子节点，运行失败会取消插入操作。

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/EajBbrM

思维导图重绘

除了使用 Mind Elixir 内核的默认行为更新思维导图，你还可以通过直接更新节点数据来重绘思维导图。

完整的节点数据结构如下：

export interface NodeObj {
  topic: string
  id: Uid
  style?: {
    fontSize?: string
    color?: string
    background?: string
    fontWeight?: string
  }
  children?: NodeObj[]
  tags?: string[]
  icons?: string[]
  hyperLink?: string
  expanded?: boolean
  direction?: Left | Right
  image?: {
    url: string
    width: number
    height: number
    fit?: 'fill' | 'contain' | 'cover'
  }
  branchColor?: string
  dangerouslySetInnerHTML?: string
  note?: string
}

通过修改节点数据可以在节点插入图片、标签、超链接等元素。举个例子，你可以通过读取 Mind Elixir 实例的 nodeData 获取到当前的思维导图数据，然后对它进行修改，最后调用 refresh 方法重绘思维导图。

const data = mind.nodeData
console.log(data)
data.topic = data.topic + 'new Data'
mind.refresh()

但是如果你想把整个思维导图更新到全新的数据呢？也可以！把符合 Mind Elixir 格式的数据传到 refresh 方法，就能立即更新全图。

import data from 'https://esm.sh/mind-elixir/dist/example.js'
mind.refresh(data)

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/vEOqpOX

重新设计的自由

Mind Elixir 赋予你重新设计思维套图的自由。

首先你可以通过 theme 和 cssVar 简单调整整个思维导图的风格。内核自带明暗两个主题 MindElixir.DARK_THEME 和 MindElixir.THEME 可供选择，如果需要自定义主题，可以按照主题格式写一个对象传入 Mind Elixir。

一个完整的 Mind Elixir 主题和使用方式如下：

const PROFESSIONAL_THEME = {
  name: 'Professional',
  type: 'light',
  palette: [
    '#2c2c2c',
    '#404040',
    '#555555',
    '#6a6a6a',
    '#7f7f7f',
    '#949494',
    '#a9a9a9',
  ],
  cssVar: {
    '--node-gap-x': '32px',
    '--node-gap-y': '12px',
    '--main-gap-x': '68px',
    '--main-gap-y': '48px',
    '--root-radius': '8px',
    '--main-radius': '6px',
    '--root-color': '#ffffff',
    '--root-bgcolor': '#1a1a1a',
    '--root-border-color': '#333333',
    '--main-color': '#2c2c2c',
    '--main-bgcolor': '#ffffff',
    '--topic-padding': '4px',
    '--color': '#4a4a4a',
    '--bgcolor': '#fafafa',
    '--selected': '#666666',
    '--panel-color': '#2c2c2c',
    '--panel-bgcolor': '#ffffff',
    '--panel-border-color': '#e0e0e0',
  },
}

let mind = new MindElixir({
  el: '#map',
  theme: PROFESSIONAL_THEME,
})

注意 data 本身也可以包含 theme，且会覆盖掉 options 中的 theme。这是为了保证每个思维导图都可以有独立的主题，如果你需要固定主题，记得在初始化时把 data 的 theme 置为 undefined。

P.S. 在初始化后想要再次修改主题，可以使用 changeTheme 方法。

cssVar 中比较常用的 main-gap 可以调整主节点间的间距：

node-gap 可以调整节点内部的间距：

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/azOgVKX

其他不能通过 css 变量调整的参数，你也可以直接通过 CSS 覆盖来微调。

在深入一点，可以通过 generateMainBranch 和 generateSubBranch 调整连线的样式。（例子请看下面 codepen 链接）

写好合适的 generateMainBranch 和 generateSubBranch 之后，如果你发现展开收缩的按钮位置不对，可以通过 CSS 进行微调。默认样式如下：

// 主节点（根节点的下一级节点）的展开收缩按钮样式
me-main > me-wrapper > me-parent > me-epd {
  top: 50%;
  transform: translateY(-50%);
}
// 其他子节点的展开收缩按钮样式
me-epd {
  top: 100%;
  transform: translateY(-50%);
}
// 左侧的展开收缩按钮专用调整
.lhs {
  & > me-wrapper > me-parent > me-epd {
    left: -10px;
  }
  me-epd {
    left: 5px;
  }
}
// 右侧的展开收缩按钮专用调整
.rhs {
  & > me-wrapper > me-parent > me-epd {
    right: -10px;
  }
  me-epd {
    right: 5px;
  }
}

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/WNmZMmq

节点样式

要是除了整体风格，你对节点也有自定义需求，节点本身是可以设置 style 的：

//...
{
  fontSize?: string
  color?: string
  background?: string
  fontWeight?: string
}
// ...

如果你对节点有非常强的自定义需求，觉得这点 style 配置根本不够用，那也没问题，还可以满足你！

你还可以通过 dangerouslySetInnerHTML 玩得更花，例如：

const data = {
  nodeData: {
    id: 'me-root',
    topic: 'Mind Elixir',
    tags: ['Mind Map Core'],
    children: [
      {
        topic: 'Customized Div',
        id: 'c00a2264f4532615',
        children: [
          {
            topic: '',
            id: 'c00a2264f4532614',
            dangerouslySetInnerHTML:
              '<div><style>.title{font-size:50px}</style><div class="title">Title</div><div style="color: red; font-size: 20px;">Hello world</div></div>',
          },
        ],
      },
    ],
  },
}

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/MYwMrjZ

导出图片

感谢 modern-screenshot，它利用 svg 巧妙地把 div 原封不动地转换为图片，基本上如果你没有搞太离谱的 dangerouslySetInnerHTML（例如视频），都能正常导出图片。@ssshooter/modern-screenshot 额外添加了 padding 选项可以调整截图的边距。

import { domToPng } from '@ssshooter/modern-screenshot'

const download = async () => {
  const dataUrl = await domToPng(mind.nodes, {
    onCloneNode: (node) => {
      const n = node as HTMLDivElement
      n.style.position = ''
      n.style.top = ''
      n.style.left = ''
      n.style.bottom = ''
      n.style.right = ''
    },
    padding: 300,
    quality: 1,
  })
  const link = document.createElement('a')
  link.download = 'screenshot.png'
  link.href = dataUrl
  link.click()
}

直接使用 modern-screenshot 或者最近才发布的 snapdom 都是可以的。如果遇到截图不完整的情况（主要是总结和连线不完整的情况）可以调整 cssVar 中的 --map-padding。

import { snapdom } from '@zumer/snapdom'

const dl2 = async () => {
  const result = await snapdom(mind.nodes)
  await result.download({ format: 'jpg', filename: 'my-capture' })
}

如果还是出现图片只截取到一部分的情况，可能是 scale 不等于 1 导致的，可以尝试在截图前设置 scale 为 1，完成后恢复原来的大小。

[!TIP] 在 Codepen 试玩：https://codepen.io/ssshooter/pen/NPqZXXB

在端渲染框架使用

在 Next.js 等后端渲染框架中使用 Mind Elixir 常常会遇到 window is not defined 之类的问题。原因是 Mind Elixir 高强度依赖各种 DOM 操作，在 SSR 的环境下是无法正常工作的。

为了解决这个问题，可以使用 useEffect 在客户端渲染时加载 Mind Elixir。下面是一个简单的示例：

'use client'
import { useEffect } from 'react'
import { mindMapExample } from './mapExample'

export const MindMap = ({ className }: { className: string }) => {
  useEffect(() => {
    import('mind-elixir').then((MindElixir) => {
      const theme = MindElixir.default.DARK_THEME
      theme.cssVar['--bgcolor'] = 'rgba(0,0,0,0)'
      const mei = new MindElixir.default({
        el: '#map',
        direction: 2,
        theme,
      })
      mei.init({
        nodeData: mindMapExample,
      })
      mei.toCenter()
      window.addEventListener('resize', () => {
        mei.toCenter()
      })
    })
  }, [])
  return (
    <div id="wrapper" className={className}>
      <div
        id="map"
        className="pointer-events-none h-[50vh] w-screen"
        onScroll={(e) => e.preventDefault()}></div>
    </div>
  )
}

其他 Mind Elixir 选项

Mind Elixir 还有很多其他选项可以配置：

interface Options {
  // ...
  direction?: number // 节点排布方向，0 左 1 右 2 两侧
  locale?: Locale // 语言选择
  contextMenu?: boolean | ContextMenuOption // 是否启用右键菜单，可添加选项
  toolBar?: boolean // 是否启动内置工具栏
  keypress?: boolean | KeypressOptions // 是否启用快捷键，可添加自定义快捷键
  mouseSelectionButton?: 0 | 2 // 拖拽按键，默认右键拖拽
  before?: Before // 上面提到的操作拦截
  newTopicName?: string // 新增节点的默认值
  allowUndo?: boolean // 是否启用撤消/重做
  overflowHidden?: boolean // 画面是否可以移动，显示思维导图卡片时可用
  alignment?: Alignment // 设为 nodes 时画面中心为思维导图中心，设为 root 时画面中心为根节点中心，默认 root
  scaleSensitivity?: number // 滚轮和菜单的放大缩小敏感度
  draggable?: boolean // 是否可以拖拽节点
  editable?: boolean // 是否可编辑
  // ...
}

结语

通过本文的介绍，相信你已经掌握了 Mind Elixir 从基础使用到高级定制的各种技巧啦。如果你在使用过程中遇到问题，或者有更好的想法和建议，可以在评论区分享，也欢迎在 GitHub 上参与讨论，提 PR！一起让 Mind Elixir 变得更完美！