企业官网建设流程全解析

Mind Elixir 是一个开源的 JavaScript 思维导图核心（mind map core），它不绑定任何前端框架，可以无缝接入 React、Vue、原生 JS 等任意技术栈。本文以官方中文文档 readme/zh.md 为主体，结合仓库源码（src/index.ts、src/types/index.ts、src/const.ts、src/utils/theme.ts 等）逐层展开，帮助你从零掌握 Mind Elixir 的安装、初始化、数据结构、事件系统、Markdown 扩展、操作守卫、图片导出、主题定制与快捷键体系，最终能在自己的项目中快速搭建一个可交互、可持久化、可定制的思维导图。

特性总览

Mind Elixir 的设计目标可以概括为四个维度：

• 用户体验：流畅直观的交互、现代简洁的界面、面向移动设备的触摸事件支持，以及为高级用户准备的键盘快捷键。
• 性能与架构：最小的打包体积、针对大型思维导图优化的高性能渲染、框架无关（可与任何前端框架配合使用）、可扩展的插件化架构。
• 核心功能：内置拖放与节点编辑、多节点批量选择与操作、完整的撤销/重做操作历史、自定义节点连接（Arrow）与内容总结（Summary）。
• 导出与定制：支持 SVG / PNG / HTML 多种导出格式、基于 CSS 变量的轻松样式化、内置主题与自定义主题。

这些能力并非空泛描述：例如“完整的操作历史”对应 src/plugin/operationHistory.ts 的实现，“多节点选择”由仓库内嵌的 viselect 模块（src/viselect/src/index.ts）驱动，而“主题支持”则由 src/const.ts 中内置的THEME/DARK_THEME与 src/utils/theme.ts 的changeTheme实现支撑。下文将逐一给出可运行的代码。

快速开始：安装与引入

Mind Elixir 提供 NPM 与 Script 标签两种安装方式，二者最终都指向同一个核心包mind-elixir。

通过 NPM 安装

npm i mind-elixir -S

然后在你的模块代码中引入：

import MindElixir from 'mind-elixir'

包管理器安装后，还需要引入配套样式。中文文档在示例中使用的是import example from 'mind-elixir/dist/example1'加载示例数据；同时，package.json的exports字段（package.json）为子路径导出了完整入口（mind-elixir）、Lite 版（mind-elixir/lite）、示例数据（mind-elixir/example）、SSR 布局工具（mind-elixir/LayoutSsr）、明文转换器（mind-elixir/plaintextConverter）、i18n 语言包（mind-elixir/i18n）以及样式入口（mind-elixir/style与mind-elixir/style.css），可以按需引入：

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

通过 Script 标签引入

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

并在你的 CSS 文件中添加：

@import 'https://cdn.jsdelivr.net/npm/mind-elixir/dist/style.css';

初始化一个思维导图

初始化是接入 Mind Elixir 的第一步。先准备一个容器元素：

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

重大变更提醒：自 1.0.0 起，data应传递给init()，而不是构造options。也就是说，new MindElixir(options)只负责创建实例与配置，真正的数据装载发生在mind.init(data)。

完整的初始化流程如下：

import MindElixir from 'mind-elixir' import { en } from 'mind-elixir/i18n' import example from 'mind-elixir/dist/example1' let options = { el: '#map', // 或 HTMLDivElement direction: MindElixir.LEFT, draggable: true, // 默认 true contextMenu: true, // 默认 true toolBar: true, // 默认 true keypress: true, // 默认 true overflowHidden: false, // 默认 false mouseSelectionButton: 0, // 0 为左键，2 为右键，默认 0 contextMenuOption: { locale: en, // [cn,zh_CN,zh_TW,en,ru,ja,pt,it,es,fr,ko,ro,da,fi,de,nl,nb,sv] focus: true, link: true, extend: [ { name: '节点编辑', onclick: () => { alert('扩展菜单') }, }, ], }, before: { insertSibling(el, obj) { return true }, async addChild(el, obj) { await sleep() return true }, }, } let mind = new MindElixir(options) mind.install(plugin) // 安装你的插件 // 创建新的地图数据 const data = MindElixir.new('new topic') // 或 `example` // 或从 `.getData()` 返回的数据 mind.init(data) // 获取一个节点 MindElixir.E('node-id')

初始化选项详解（源码级）

对照 src/types/index.ts 的Options接口，各选项的类型与默认值如下：

这些默认值在 src/index.ts 的构造函数中通过??运算符逐一落实，例如this.direction = direction ?? 1、this.scaleMin = scaleMin ?? 0.2。此外，构造函数还会根据prefers-color-scheme自动选择初始主题：this.theme = (theme || (mediaQuery.matches ? DARK_THEME : THEME))。

方向常量与示例数据

四个方向常量LEFT/RIGHT/SIDE/DOWN定义于 src/const.ts，对应值分别为0 / 1 / 2 / 3，同时作为MindElixir的静态属性暴露（src/index.ts）。仓库在 src/exampleData 目录下提供了多套可直接导入的示例数据（如1.cn.ts、1.ts、org.ts等），方便你快速体验不同布局与结构。

数据结构：节点对象规范

Mind Elixir 的数据模型是标准的树形结构。截至当前版本，单个节点（NodeObj）的完整结构如下：

// 到目前为止的整个节点数据结构 const nodeData = { topic: '节点主题', id: 'bd1c24420cd2c2f5', style: { fontSize: '32', color: '#3298db', background: '#ecf0f1' }, expanded: true, parent: null, tags: ['标签'], icons: ['😀'], hyperLink: 'https://github.com/ssshooter/mind-elixir-core', image: { url: 'https://raw.githubusercontent.com/ssshooter/mind-elixir-core/master/images/logo2.png', // 必填 // 你需要查询图片的高度和宽度，并计算显示图片的适当值 height: 90, // 必填 width: 90, // 必填 }, children: [ { topic: '子节点', id: 'xxxx', // ... }, ], }

对照 src/types/index.ts 的NodeObj接口，除了文档示例中的字段，还存在以下常用可选字段：

• branchColor：分支连线颜色；
• dangerouslySetInnerHTML：在节点内渲染自定义 HTML，会替换节点内的所有内容；
• note：节点备注；
• metadata：任意类型的泛型元数据；
• image.fit：图片填充模式，取值为'fill' | 'contain' | 'cover'；
• tags：既可以是字符串数组，也可以是TagObj（{ text, style?, className? }），从而为标签附加内联样式；
• style：支持fontSize、fontFamily、color、background、fontWeight、width、border、textDecoration；
• direction：0 | 1，用于SIDE（左右分布）布局时指定节点挂在左侧还是右侧。

需要注意：parent字段由框架在init时通过fillParent递归补齐（见 src/methods.ts），不要手动设置；根节点的parent为null。顶层数据结构MindElixirData（src/types/index.ts）除nodeData外还包含arrows（连线）、summaries（摘要）、direction、theme、compact与meta（地图级任意元数据）。

事件处理：基于总线（Bus）的订阅模型

Mind Elixir 内部实现了一个轻量的发布订阅总线（src/utils/pubsub.ts），所有实例都暴露mind.bus，支持addListener、fire、removeListener三个方法。常用事件监听写法：

mind.bus.addListener('operation', operation => { console.log(operation) // 返回 { // name: 操作名称, // obj: 目标对象 // } // name: [insertSibling|addChild|removeNode|beginEdit|finishEdit] // obj: 目标 // name: moveNode // obj: {from:目标1,to:目标2} }) mind.bus.addListener('selectNodes', nodes => { console.log(nodes) }) mind.bus.addListener('expandNode', node => { console.log('expandNode: ', node) })

src/utils/pubsub.ts 定义的完整事件表还包括：selectNewNode、unselectNodes、changeDirection、linkDiv、scale、move、updateArrowDelta、selectArrow、unselectArrow、selectSummary、unselectSummary、showContextMenu。其中operation事件是接入业务持久化、审计、同步协作的关键通道——例如官方操作历史插件正是监听operation事件来记录快照的（见 src/plugin/operationHistory.ts）。updateArrowDelta的注释特别提示：该事件触发频繁，请使用节流（throttling）防止性能退化。

数据导出与导入

// 数据导出 const data = mind.getData() // JavaScript 对象，见 src/example.js mind.getDataString() // 字符串化对象 // 数据导入 // 初始化 let mind = new MindElixir(options) mind.init(data) // 数据更新 mind.refresh(data)

• getData()返回MindElixirData对象，可整体序列化存入后端或 localStorage；
• getDataString()内部调用stringifyData（实现见 src/interact.ts），返回 JSON 字符串；
• init(data)用于首次装载，内部会JSON.parse(JSON.stringify(data))深拷贝数据、填充parent引用、按data.theme/data.compact/data.direction覆盖实例配置（src/methods.ts）；
• refresh(data)用于更新已有实例的数据。

仓库还提供了「思维导图 ⇄ 明文（Markdown/大纲）」双向转换能力：mind-elixir/plaintextConverter子路径导出转换器，对应源码 src/utils/plaintextConverter.ts、src/utils/plaintextToMindElixir.ts 与 src/utils/mindElixirToPlaintext.ts，并有配套测试 tests/plaintext-parser.spec.ts 保障解析正确性，可用于导入/导出大纲文本。

Markdown 支持

Mind Elixir 本身默认不启用Markdown 渲染（markdown选项省略即不处理），但提供两种接入方式：

// 禁用 markdown（默认） let mind = new MindElixir({ // 省略 markdown 选项 - 不进行 markdown 处理 }) // 使用自定义 markdown 解析器 let mind = new MindElixir({ markdown: text => { // 你的自定义 markdown 实现 return text .replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>') .replace(/\*(.*?)\*/g, '<em>$1</em>') .replace(/`(.*?)`/g, '<code>$1</code>') }, }) // 使用任何 markdown 库（例如 marked、markdown-it 等） import { marked } from 'marked' let mind = new MindElixir({ markdown: text => marked(text), })

从类型定义看（src/types/index.ts），markdown回调的完整签名是(markdown: string, obj: NodeObj | Arrow | Summary) => string，第二个参数会告诉你当前渲染的是节点、连线还是摘要，便于为不同对象差异化处理。仓库自带 src/markdown.css 为渲染后的 HTML 提供基础排版样式，并在src/index.ts中一并引入。此外，skills/customize-markdown/SKILL.md 提供了关于自定义 Markdown 渲染的专项说明。

操作守卫：before 钩子

在节点插入、移动、删除等操作真正执行前，Mind Elixir 允许你通过before选项插入校验逻辑。钩子返回false（或 resolve 为false的 Promise）即可否决该操作：

let mind = new MindElixir({ // ... before: { insertSibling(el, obj) { console.log(el, obj) if (this.currentNode.nodeObj.parent.root) { return false } return true }, async addChild(el, obj) { await sleep() if (this.currentNode.nodeObj.parent.root) { return false } return true }, }, })

从源码看，before的实现机制非常优雅：src/methods.ts中的beforeHook将nodeOperation里的每个操作方法包装成「先跑钩子、通过后再执行原方法」的异步函数（src/methods.ts），并通过Object.assign混入MindElixir.prototype。Before类型定义（src/types/index.ts）表明：每一个节点操作方法都有对应的守卫钩子，且钩子内this指向当前MindElixir实例，因此可以在守卫中访问this.currentNode、this.getData()等实例成员。典型应用场景包括：根节点不可删除、异步校验权限/数据库写入成功后放行（英文文档示例中即展示了await saveDataToDb()后再返回true的写法）。

导出为图片

自 v5 起，官方推荐使用@zumer/snapdom对节点 DOM 进行截图导出：

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

mind.nodes是包含整张思维导图渲染结果的 DOM 容器（在 src/index.ts 中创建为me-nodes元素），把它交给snapdom即可得到图片并触发下载。

已弃用的 API

⚠️已弃用：mind.exportSvg()方法已弃用，将在未来版本中移除。

// 已弃用 - 请不要在新项目中使用 const svgData = await mind.exportSvg()

源码侧的证据同样明确：src/plugin/exportImage.ts中的exportSvg与exportPng都带有@deprecatedJSDoc 注释（src/plugin/exportImage.ts），并建议改用 modern-screenshot 方案。如果你想理解旧方案的原理，可以阅读generateSvg：它遍历me-nodes下的me-tpc节点、标签、图标、超链接与图片，将每个 DOM 节点转换为对应的 SVG 元素（rect、text、foreignObject、a、image），再组合主线、子线、连线与摘要图层，最后以image/svg+xml的 Blob 返回；exportPng则在此基础上将 SVG 转为 data URL 再绘制到 canvas，并利用 base64 绕过 canvas 污染（src/plugin/exportImage.ts）。仓库另外维护了独立的 HTML 导出生态包@mind-elixir/export-html，可在 readme.md 的生态一节查看。

主题定制

Mind Elixir 的主题由「调色板 + CSS 变量」两部分构成，可在初始化时传入，也可在运行时用changeTheme切换：

const options = { // ... theme: { name: 'Dark', // 主线颜色调色板 palette: ['#848FA0', '#748BE9', '#D2F9FE', '#4145A5', '#789AFA', '#706CF4', '#EF987F', '#775DD5', '#FCEECF', '#DA7FBC'], // 覆盖 CSS 变量 cssVar: { '--main-color': '#ffffff', '--main-bgcolor': '#4c4f69', '--color': '#cccccc', '--bgcolor': '#252526', '--panel-color': '255, 255, 255', '--panel-bgcolor': '45, 55, 72', }, // 所有变量见 /src/index.less }, // ... } // ... mind.changeTheme({ name: 'Latte', palette: ['#dd7878', '#ea76cb', '#8839ef', '#e64553', '#fe640b', '#df8e1d', '#40a02b', '#209fb5', '#1e66f5', '#7287fd'], cssVar: { '--main-color': '#444446', '--main-bgcolor': '#ffffff', '--color': '#777777', '--bgcolor': '#f6f6f6', }, })

请注意，Mind Elixir不会观察prefers-color-scheme的变化。当系统明暗方案变化时，请手动调用changeTheme切换主题。

主题机制的源码解读

• 内置主题：src/const.ts 定义了浅色THEME（Latte）与深色DARK_THEME（Dark），并导出完整的cssVar变量集（--node-gap-x、--main-gap-x、--root-color、--selected、--accent-color、--map-padding等），同时以MindElixir.THEME/MindElixir.DARK_THEME静态属性暴露（src/index.ts）。
• 合并策略：src/utils/theme.ts 的changeTheme会先以theme.type === 'dark'为基准取内置深/浅主题的cssVar，再用自定义cssVar覆盖合并，最后通过container.style.setProperty逐项写入；shouldRefresh参数默认为true，即切换主题后自动重绘。
• 紧凑模式联动：当compact为true时，changeTheme会额外强制覆盖间距变量为--node-gap-x: 15px、--main-gap-x: 30px等小值（src/utils/theme.ts）；运行时可用changeCompact(boolean)动态切换。
• 主题级分支生成器：Theme类型支持在主题内携带generateMainBranch/generateSubBranch，changeTheme会同步替换实例的分支连线生成函数（src/utils/theme.ts），默认实现见 src/utils/generateBranch.ts。

快捷键

Mind Elixir 内置了一套面向键盘重度用户的快捷键体系，其完整映射实现在 src/plugin/keypress.ts。常用键位如下：

细节补充：

• 方向键的逻辑分支在 src/plugin/keypress.ts：左右布局下←/→负责层级跳转（根节点按左右侧选区中间节点、进入子节点、返回父节点），↑/↓负责同级前后切换；而在DOWN（自上而下）布局中语义互换。
• Ctrl+K是复合快捷键序列的起始键：按下后 2 秒内未接续按键会自动取消（src/plugin/keypress.ts）。
• 快捷键通过keypress: true默认启用；若传入对象，则对象中的键位会覆盖默认映射（...options展开，见 src/plugin/keypress.ts），适合按产品需求定制。
• 官方快捷键指南详见文档站，仓库的 tests 目录（如 tests/keyboard-undo-redo.spec.ts）也包含针对键盘行为的 Playwright 回归测试。

撤销 / 重做

撤销与重做是「核心功能」中完整操作历史的具体体现，实现位于 src/plugin/operationHistory.ts：

• 每个操作都会被记录为{ prev, next, operation, currentSelected, currentTarget }快照，prev/next分别是操作前后的整份MindElixirData；
• mind.undo()/mind.redo()通过refresh()恢复对应快照，并尽力恢复操作前后的选中节点（例如删除类操作撤销后选中被恢复的节点）；
• 监听operation、selectNodes、unselectNodes事件维护选中状态，Ctrl/Cmd+Z撤销、Ctrl/Cmd+Shift+Z或Ctrl/Cmd+Y重做（使用e.code物理按键匹配，规避输入法与 CapsLock 干扰，见 src/plugin/operationHistory.ts）；
• allowUndo默认为true；当设为false时撤销能力关闭。加载新数据后若不想让用户一路撤销回旧图，可调用mind.clearHistory()重置历史栈与基线快照（src/index.ts）。

插件体系与常用生态

插件化是 Mind Elixir 架构的核心卖点。mind.install(plugin)接收一个以实例为参数的函数：

mind.install(plugin) // 安装你的插件

内部实现为install: (this, plugin) => plugin(this)，即插件获得完整实例引用，可自由订阅mind.bus事件、调用公开方法或扩展 DOM。仓库自带工具栏、右键菜单、快捷键、拖拽、历史记录、导出等插件，全部位于 src/plugin 目录；例如 src/plugin/contextMenu.ts 支持通过contextMenuOption.extend追加自定义菜单项（中文文档示例中的「节点编辑」菜单即由此实现）。

官方维护的周边生态包括：

• @mind-elixir/node-menu/@mind-elixir/node-menu-neo：节点右键菜单增强；
• @mind-elixir/export-xmind：导出 XMind 格式；
• @mind-elixir/export-html：导出 HTML；
• mind-elixir-react：React 封装。

开发与构建

如果你想在本地开发或贡献代码，仓库使用 pnpm 管理依赖（见 pnpm-workspace.yaml）：

pnpm i pnpm dev

使用dev.dist.ts测试生成的文件：

pnpm build pnpm link ./

更新 API 文档（基于@microsoft/api-extractor）：

# 安装 api-extractor pnpm install -g @microsoft/api-extractor # 维护 /src/docs.ts # 生成文档 pnpm doc pnpm doc:md

重新生成MindElixir类成员：

MindElixir类的选项与方法声明（src/index.ts 中的// #region GENERATED区块）由 gen-members.js 基于dist/types中的编译产物生成，从而让发布的.d.ts和 API 文档展示完整展开的签名。修改混入方法（src/methods.ts）或Options接口（src/types/index.ts）后，请执行：

pnpm tsc # 生成最新的 dist/types pnpm gen:members # 重写 src/index.ts 中的生成区块

src/index.ts底部的编译期守卫（_MethodsDeclared、_OptionsDeclared、_MethodsInSync、_OptionsInSync，见 src/index.ts）会在区块不同步时让tsc失败，因此忘记重新生成也会被及时发现。

结语

从安装引入、实例初始化、数据建模，到事件订阅、操作守卫、Markdown 扩展、图片导出、主题定制与快捷键，Mind Elixir 以「框架无关的核心 + 插件化架构」提供了完整的思维导图解决方案。本文中的每一项能力都能在仓库源码中找到对应实现（如 src/methods.ts、src/plugin 目录、tests 目录的回归测试），建议你在实际项目中边用边读源码，必要时直接以插件形式扩展自己的功能。