企业官网建设流程全解析

本篇文章以仓库 CHANGELOG.md 为骨架，系统梳理 Mind Elixir Core v5 系列（5.5.0 – 5.15.0）的每一次功能性、破坏性与重构性变更，并结合src/目录下的源码实现、类型定义与测试用例进行纵深剖析。读完你将掌握：refresh与主题系统的解耦关系、基于 Pointer Events 的交互状态机演进、reshapeArrow等箭头编程接口、plaintext 双向转换器的无损往返机制，以及从 v5.9 / v5.10 迁移到最新版本时必须处理的破坏性变更。

一、版本时间线与能力全景

CHANGELOG 覆盖了从 5.5.0 到 5.15.0 共约 21 个版本，其中 5.15.0 标注为Unreleased（未发布），5.5.0 只有标题没有明细条目。按主题归类，各版本核心内容如下：

下面按技术主题深入展开。

二、主题系统：从「与 refresh 耦合」到「完全解耦」

2.1 破坏性变更：refresh(data)不再应用data.theme

5.15.0（Unreleased）引入了 v5 后期最重要的破坏性变更：

refresh(data)不再应用data.theme。主题处理与refresh完全解耦，需要切换主题时必须显式调用changeTheme(theme)。

也就是说，以下旧写法不再生效：

// 旧行为：refresh 会顺带应用 data 中的主题 mind.refresh(data) // 新行为：主题不再被 refresh 隐式应用 mind.refresh(data) if (data.theme) { mind.changeTheme(data.theme) }

从源码可以印证这一设计。在 src/methods.ts 的init实现中，主题的注入被显式限定在初始化阶段，并且明确传入了shouldRefresh = false以避免重复刷新：

init(this: MindElixirInstance, data: MindElixirData) { data = JSON.parse(JSON.stringify(data)) // ... this.changeTheme(data.theme || this.theme, false) // ... this.layout() this.linkDiv() this.toCenter() }

而changeTheme的第二个参数shouldRefresh正是解耦的关键。在 src/utils/theme.ts 中：

export const changeTheme = function (this: MindElixirInstance, theme: Theme, shouldRefresh = true) { this.theme = theme as MindElixirInstance['theme'] this.generateMainBranch = this.theme.generateMainBranch || main this.generateSubBranch = this.theme.generateSubBranch || sub const base = this.theme.type === 'dark' ? DARK_THEME : THEME const cssVar = { ...base.cssVar, ...this.theme.cssVar } // ... const keys = Object.keys(cssVar) for (let i = 0; i < keys.length; i++) { const key = keys[i] as keyof typeof cssVar this.container.style.setProperty(key, cssVar[key] as string) } shouldRefresh && this.refresh() }

从这段实现可以推断 5.15.0 的意图：refresh只负责「重绘数据」，changeTheme只负责「换肤」，两者各司其职，避免refresh隐式换肤带来的副作用（例如批量刷新数据时意外切换主题）。

2.2 修复：undo/redo不再重置当前主题

与 2.1 同版本修复的另一个问题解释了「为什么之前 refresh 不能碰主题」：

undo/redo不再重置当前主题。主题函数（generateMainBranch/generateSubBranch）无法通过历史快照的 JSON 序列化存活，所以此前执行 undo 会把自定义分支样式还原为默认。

撤销/重做的实现位于 src/plugin/operationHistory.ts。其历史栈保存的是prev/next两份MindElixirData快照，而init中data = JSON.parse(JSON.stringify(data))说明数据在初始化时就会经历 JSON 序列化——函数类型的generateMainBranch/generateSubBranch会被序列化过程丢弃。因此 undo 时若refresh隐式地重新应用「来自快照的 theme」，自定义的分支生成函数自然就丢了；解耦之后，refresh只重绘节点树与连线，主题状态（包括函数）由changeTheme独立维护，撤销也就不会再把分支样式还原成默认。

同时，changeTheme内部会在设置主题时重新绑定this.generateMainBranch/this.generateSubBranch（回退到 src/utils/generateBranch.ts 内置的main/sub），这保证了「先换肤、后重绘」的调用顺序始终有效。

2.3 主题定义升级：必需的cssVar属性（5.13.0）

5.13.0 将主题定义扩展为必需的cssVar属性。内置的亮色/暗色主题在 src/const.ts 中定义，两者都携带完整的 CSS 变量表，例如默认亮色主题THEME：

export const THEME: Theme & { cssVar: ThemeCssVar } = { name: 'Latte', type: 'light', palette: ['#dd7878', '#ea76cb', '#8839ef', '#e64553', '#fe640b', '#df8e1d', '#40a02b', '#209fb5', '#1e66f5', '#7287fd'], cssVar: { '--node-gap-x': '30px', '--node-gap-y': '10px', '--main-gap-x': '65px', '--main-gap-y': '45px', '--root-radius': '30px', '--main-radius': '20px', '--root-color': '#ffffff', '--root-bgcolor': '#4c4f69', '--root-border-color': 'rgba(0, 0, 0, 0)', '--main-border': '', '--main-color': '#444446', '--main-bgcolor': '#ffffff', '--main-bgcolor-transparent': 'rgba(255, 255, 255, 0.8)', '--topic-padding': '3px', '--color': '#777777', '--bgcolor': '#f6f6f6', '--selected': '#4dc4ff', '--accent-color': '#e64553', '--panel-color': '#444446', '--panel-bgcolor': '#ffffff', '--panel-border-color': '#eaeaea', '--map-padding': '50px 80px', }, }

完整的变量清单定义在 src/types/index.ts 的ThemeCssVar类型中（唯一可省略的是--main-border，其注释说明未设置时会回退为2px solid main-color）。changeTheme的合并策略是：先取type === 'dark' ? DARK_THEME : THEME作为基座，再用用户主题的cssVar覆盖——这意味着你只需要覆盖想要改变的变量，其余变量自动继承对应亮/暗基座。

自定义主题示例（与 readme.md 的用法一致）：

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。

2.4 自定义分支渲染与 metadata（5.12.2）

5.12.2 新增了自定义分支渲染与 metadata 支持。Theme类型（src/types/index.ts）允许通过generateMainBranch/generateSubBranch两个函数完全接管分支 SVG 的生成逻辑：

export type Theme = { name: string type?: 'light' | 'dark' palette: string[] cssVar?: Partial<ThemeCssVar> generateMainBranch?: (this: MindElixirInstance, params: MainLineParams) => string generateSubBranch?: (this: MindElixirInstance, params: SubLineParams) => string }

对应的参数类型MainLineParams/SubLineParams定义在 src/utils/generateBranch.ts，并随MindElixirMethods一并导出。同时NodeObj增加了泛型metadata字段（metadata?: M），可承载任意自定义业务数据，且Arrow、Summary也具备各自的metadata，这为插件与业务方按需扩展数据结构提供了统一入口。

2.5 compact 紧凑模式（5.12.0 / 5.12.1）

5.12.0 加入 compact 模式，用于可配置的节点间距压缩；5.12.1 进一步支持在MindElixirData中序列化与恢复 compact 状态。

• 构造选项：compact?: boolean（src/types/index.ts 中Options，注释明确「若为 true，间距字段将被控制为较小值」）；
• 数据序列化：MindElixirData新增compact?: boolean顶层字段，init时会读取data.compact并应用到实例（见 src/methods.ts）；
• 运行时切换：changeCompact(compact)方法（src/utils/theme.ts）：

export const changeCompact = function (this: MindElixirInstance, compact: boolean) { this.compact = compact if (this.theme) { this.changeTheme(this.theme) } }

compact 模式的实际效果体现在changeTheme内部的间距覆盖逻辑中：

if (this.compact) { cssVar['--node-gap-x'] = '15px' cssVar['--node-gap-y'] = '2px' cssVar['--main-gap-x'] = '30px' cssVar['--main-gap-y'] = '6px' }

也就是说，compact 模式会将水平/垂直的节点间距与主分支间距压缩到默认值（30px/10px与65px/45px）的一半以下，适用于信息密度较高的场景。注意：由于 compact 依赖重新计算 CSS 变量，切换后主题会以shouldRefresh = true触发一次刷新。

三、交互体系重构：Pointer Events 与状态机（5.11.x）

5.11.x 系列是交互底层的大重构窗口，核心方向是「统一事件模型 + 显式状态机」。

3.1 状态机与 Pointer Events 迁移

5.11.2 的 Refactors 包括：引入状态机管理指针交互、CanvasPointerDown状态协调画布交互与选择逻辑、将鼠标/触摸事件全面迁移为 Pointer Events、封装触摸捏合与平移逻辑为独立 helper、把linkSvgGroup重命名为arrowSvg并统一 SVG 类型与箭头组 ID、聚合长按逻辑到longPressHelper对象。

源码证据在 src/mouse.ts：State枚举定义了Idle / Pinch / DragWait / Drag / Pan / BoxSelect六个显式状态，doubleClickHelper使用 PointerEvent 进行双击判定，pinchHelper通过activePointersMap 跟踪多指并计算距离比例缩放，longPressHelper则以DURATION: 500毫秒、MOVE_THRESHOLD: 10像素判定长按——这些都是上述重构的落地实现。

5.11.0 同时将点击与双击事件迁移到 pointer events（此前 click/dblclick），并把节点选择逻辑统一收拢到mouse.ts，把dragmove事件更名为pan。

3.2 双击与右键菜单细节修复（5.11.3）

5.11.3 修复了两个交互边界问题：

1. 忽略非左键的双击判定：doubleClickHelper.detect开头即检查e.button !== 0并clear()，防止鼠标中键/右键触发双击编辑；
2. 编辑或交互状态下阻止右键菜单：节点处于编辑/交互状态时不再弹出上下文菜单，避免菜单与输入框互相干扰。

3.3 移动端拖拽中止回退（5.14.0）

5.14.0 修复：移动端在DragWait状态（等待拖拽判定）下中止节点拖拽时，回退为地图平移，而不是卡死在「想拖又拖不动」的状态。DragWait作为独立状态存在于 src/mouse.ts 的State中，这保证了触屏上「长按等待 → 决定是拖节点还是拖地图」的决策路径是确定的。

3.4 只读模式行为修正

• 5.11.2 修复只读模式（readonly）下的行为异常；
• 5.8.2 允许只读模式下使用两个鼠标按键进行画布拖拽（此前可能仅限特定按键）；
• 5.9.3 支持动态切换拖拽与选择功能的开关。

四、i18n 体系调整（5.10.0，破坏性变更）

5.10.0 将语言配置从顶层Options迁移到contextMenu.locale，这是 v5 中另一个必须关注的破坏性变更：

• 顶层Options.locale现在只接受语言代码（string），并且已标记deprecated；
• 自定义翻译或设置语言请使用contextMenu: { locale: LangPack }；
• 预置语言包（如en、zh_CN）通过新的i18n导出可用。

语言包类型LangPack定义在 src/i18n.ts，包含addChild、addParent、addSibling、removeNode、focus、cancelFocus、moveUp、moveDown、link、linkBidirectional、clickTips、summary共 12 个文案键。仓库中已提供cn（即zh_CN）、zh_TW、en、ru、ja等语言包，对应 readme.md 中列出的支持清单[cn,zh_CN,zh_TW,en,ru,ja,pt,it,es,fr,ko,ro,da,fi,de,nl,nb,sv]。

新写法示例：

import MindElixir from 'mind-elixir' import { en } from 'mind-elixir/i18n' let mind = new MindElixir({ el: '#map', contextMenu: { locale: en, // 取代顶层 locale 选项 focus: true, link: true, extend: [ { name: 'Node edit', onclick: () => alert('extend menu'), }, ], }, })

五、箭头（Arrow）系统升级：编程化 reshape 与 delta 计算

5.1reshapeArrow：程序化更新箭头属性（5.14.0）

5.14.0 实现了reshapeArrow工具，支持以编程方式更新连接箭头的属性（style、label、delta 等），并触发reshapeArrow操作事件。接口签名（src/index.ts 的声明与 src/arrow.ts 的实现）：

mind.reshapeArrow(arrow, patchData) // arrow: Arrow, patchData: Partial<Arrow>

实现要点（src/arrow.ts）：

• 先对原箭头做deepClone保存origin，用于操作历史；
• style采用「浅合并」：Object.assign({}, origin.style, patchData.style)，因此只更新stroke不会丢失原有的strokeDasharray；
• 若patchData.label发生变化，会通过this.markdown重新渲染 label（与节点一致支持自定义 markdown）；
• 若箭头缺少delta1/delta2，会调用calculateDefaultDeltas自动补全；
• 若箭头当前处于选中状态（currentArrow匹配），控制点手柄与辅助线会同步原位更新；
• 最后bus.fire('operation', { name: 'reshapeArrow', obj: arrow, origin })。

Arrow数据模型（src/arrow.ts）可编程修改的字段包括：

ArrowStyle各字段的默认值在渲染路径中可见：默认描边rgb(227, 125, 116)、线宽2、虚线8,2、线帽cap、标签色rgb(235, 95, 82)。

5.2 控制点拖拽也纳入历史（5.14.0）

reshapeArrow不仅是一个公开 API，还是「控制点拖拽」这一交互的底层记录机制。在 src/arrow.ts 的showLinkController中，拖动 P2/P3 控制点结束后会触发：

const handleDragEnd = () => { bus.fire('operation', { name: 'reshapeArrow', obj: linkItem, origin: dragOrigin, }) dragOrigin = deepClone(linkItem) }

这意味着通过手柄拖拽调整箭头曲率，同样会被 src/plugin/operationHistory.ts 记录为可撤销/重做的reshapeArrow操作（其calcCurentObject明确将reshapeArrow归类为arrow类型的目标对象）。

5.3 delta 自动计算与整数值（5.6.0 / 5.11.0）

• 5.6.0 起「计算箭头 delta 而非常量值」：calculateDefaultDeltas（src/arrow.ts）根据两节点的中心向量与距离自动推导控制点偏移——距离的 30% 作为基准偏移（Math.max(50, Math.min(200, distance * 0.3))），并按「近距离 C 型曲线 / 水平 / 垂直 / 对角」四种几何关系分支计算；
• 5.6.0 同时修复箭头反转问题（calcP通过斜率与宽高比判断出线边，避免箭头从错误一侧穿出）；
• 5.11.0 将 delta 值四舍五入为整数，避免浮点抖动导致 SVG 路径在缩放/拖拽后出现亚像素偏差；
• 5.7.0 支持创建无偏移箭头（createArrow(from, to, { style })不传 delta 时由drawArrow自动补全默认值）；
• 5.11.2 新增 summary 与 arrow 相关事件（selectArrow/unselectArrow/updateArrowDelta等，见 src/arrow.ts 中各bus.fire调用点）。

5.4 箭头高亮修复

• 5.9.0 修复箭头高亮反复显示的问题：updateArrowHighlight会在重绘路径时同步刷新已存在的高亮层，hideLinkController在取消选择时统一移除高亮（src/arrow.ts）；
• 5.6.0 更新.svg-label样式并增强全屏处理，箭头标签位置由贝塞尔曲线中点公式计算。

六、Plaintext 双向转换器：从导出到无损往返

plaintext 转换器是 v5 中后期最活跃的功能线之一，演进路径为：5.7.0 首次加入 → 5.8.0 构建并导出 → 5.8.2 支持更多样式 → 5.8.3 重构算法 → 5.9.0 新增反向转换并优化算法 → 5.10.0 保留箭头 delta 坐标。

6.1 转换器架构

转换器最终沉淀为两个导出函数：

• plaintextToMindElixir(plaintext, rootName = 'Root')：src/utils/plaintextToMindElixir.ts
• mindElixirToPlaintext(data)：src/utils/mindElixirToPlaintext.ts

完整的格式规范与算法说明可参考 refs/plaintext-converter.md。

6.2 Plaintext 语法速查

• 节点：- Topic，每级缩进 2 个空格；
• 引用 ID：- Node A [^my-ref]，供箭头引用；解析后存入node.metadata.refId；
• 样式：- Styled Node {"color": "#e87a90", "fontSize": "18px"}，支持NodeObj.style全部字段；
• 箭头：以>开头，两种连接符：

• Summary：以}开头，}:N label概括当前位置往前 N 个兄弟节点，} label概括之前所有兄弟节点。

6.3 箭头 delta 坐标的保留（5.10.0）

5.10.0 让 plaintext 转换器保留箭头 delta 坐标(x, y)。序列化时（src/utils/mindElixirToPlaintext.ts）：

- > [^node-2-1] (10,20) <-Bidirectional Link-> (30,40) [^id2]

解析时（src/utils/plaintextToMindElixir.ts 的parseArrow）通过正则\[\^([\w-]+)\](?:\s*\(([\d.-]+),([\d.-]+)\))?\s*<-([^-]*)->(?:\s*\(([\d.-]+),([\d.-]+)\))?\s*\[\^([\w-]+)\]提取两侧的 delta，从而在导入后保留箭头曲率。

6.4 无损往返（Roundtrip）与 slots 模型

转换器的核心设计目标是无损往返：plaintext → MindElixir → plaintext还原出完全相同的文本。关键机制（详见 refs/plaintext-converter.md）：

mindElixirToPlaintext内部使用PtTree+slots模型：children只保存纯节点骨架，slots[i]作为「打印第 i 个子节点之前要优先输出的箭头/摘要信箱」。这种「绝对坐标锁定」设计从根本上解决了早期算法中因列表拼接导致的下标偏移错乱。

测试层面，tests/plaintext-parser.spec.ts 覆盖了解析与序列化的往返一致性。

七、剪贴板与输入体验优化（5.7.x / 5.9.x）

7.1 剪贴板重构（5.7.0 / 5.7.1）

5.7.0 将剪贴板处理重构为原生事件驱动，并引入pasteHandler选项（Options.pasteHandler?: (e: ClipboardEvent) => void，src/types/index.ts）。实现位于 src/plugin/keypress.ts：

• copy/cut：通过handleSetNodesClip将选中节点序列化为带魔数的 JSON（MIND-ELIXIR-WAIT-COPY）写入text/plain，实现跨实例/跨页面复制；
• paste：优先解析带魔数的内部格式并执行copyNodes；若解析失败（外部文本），则降级到pasteHandler回调，方便接入外部剪贴板内容（如纯文本导入）；
• 5.7.1 修复输入框中的复制行为（避免键盘拦截影响<input>内的复制粘贴）。

7.2 IME 组合输入保护（5.13.0）

5.13.0 在 DOM 与 SVG 两套事件处理器中增加e.isComposing检查，防止中文等输入法组合期间触发快捷键或节点操作。源码证据：src/utils/dom.ts 与 src/utils/svg.ts 中均有if (e.isComposing) return。

7.3 其他输入修复

• 5.9.2：修复 Safari 中可编辑内容（contenteditable）的换行符转换；
• 5.9.3：Esc键退出节点编辑；
• 5.7.1：输入框复制行为。

7.4 快捷键速览（源码依据 src/plugin/keypress.ts）

KeypressOptions允许通过keypress: { 自定义键: fn }扩展或覆盖快捷键表。

八、缩放、手势与移动端 UX

• 5.11.0 改善 Magic Trackpad UX：滚轮事件中normalizeWheelDelta专门处理DOM_DELTA_LINE（触控板行增量，WHEEL_ZOOM_LINE_HEIGHT = 40）与DOM_DELTA_PAGE（页增量）两种模式，将不同设备的滚轮语义统一换算为像素，再经getWheelZoomScaleDelta钳制到[-scaleSensitivity, scaleSensitivity]区间（src/plugin/keypress.ts）；
• 5.9.1 改善捏合手势 UX：pinchHelper在双指距离变化时按比例缩放并围绕双指中点缩放（src/mouse.ts）；
• 5.11.2 新增forceCenter参数与enableMobileMultiSelect：scrollIntoView(el, forceCenter = false)（src/interact.ts）在强制居中模式下滚动到节点；enableMobileMultiSelect(enable)（src/methods.ts）运行时开关移动端多选；
• 5.6.0 增强全屏处理并改进 scale 校验逻辑（scaleMin/scaleMax选项可约束缩放范围）。

九、SSR 与工程化改进

• 5.6.1：统一地图 padding（50px→50px 80px），并导出常量LEFT、RIGHT、SIDE、THEME、DARK_THEME以绕开 SSR 下的报错——这些常量定义在 src/const.ts；
• 5.9.1：移除顶层作用域的document引用，避免 SSR 应用在服务端渲染阶段立即报错；
• 5.11.2：统一 blur 与 pointer cancel 处理器，优化节点拖拽幽灵（ghost）定位；
• 5.11.0：改善测试在 macOS 上的兼容性并延长超时。

这些工程化改动使 Mind Elixir Core 在服务端渲染框架（如 Next.js、Nuxt）中能够安全地作为纯客户端组件被动态引入。

十、升级迁移速查

针对 v5 中两个破坏性变更（5.10.0 与 5.15.0），迁移要点如下：

从 ≤5.9 升级到 ≥5.10.0：

// 旧写法（顶层 locale，已废弃） new MindElixir({ el: '#map', locale: 'en' }) // 新写法 import { en } from 'mind-elixir/i18n' new MindElixir({ el: '#map', contextMenu: { locale: en } })

从 ≤5.14 升级到 5.15.0（Unreleased）：

// 旧写法：refresh 隐式应用主题 mind.refresh(data) // 新写法：显式分离 mind.refresh(data) if (data.theme) mind.changeTheme(data.theme)

同时注意：

• draggable选项已废弃（5.7.0 移除），统一使用editable；
• 若使用getData()/init()在实例间搬运数据，compact 状态（5.12.1 起）与主题状态现在会随MindElixirData序列化/恢复，但主题函数仍不会被序列化，跨实例迁移自定义分支渲染函数时需在目标实例上重新通过theme.generateMainBranch配置；
• 需要撤销/重做时保持allowUndo: true（默认开启），并在加载新数据后调用clearHistory()防止撤销回旧图（src/index.ts 中clearHistory的文档说明）。

十一、测试保障

仓库 tests/ 目录对上述能力有系统性覆盖，可作为回归验证的入口：

• tests/plaintext-parser.spec.ts：plaintext 转换器解析与往返；
• tests/arrow.spec.ts 与 tests/summary.spec.ts：箭头与摘要的创建/编辑/移除；
• tests/operation-history.spec.ts、tests/undo-redo.spec.ts、tests/simple-undo-redo.spec.ts、tests/keyboard-undo-redo.spec.ts：撤销/重做栈行为；
• tests/mobile-multi-select.spec.ts：移动端多选；
• tests/multiple-instance.spec.ts：多实例隔离（含剪贴板跨实例粘贴）；
• tests/interaction.spec.ts：节点增删改查与快捷键交互。

这些测试使用 Playwright 驱动真实浏览器（配置见 playwright.config.ts），快照目录下同时维护 darwin 与 win32 两套平台截图，正是 5.11.0「改善测试跨平台兼容性」的产物。

结语

从 5.5.0 到 5.15.0，Mind Elixir Core 完成了一次「从功能堆叠到架构收敛」的升级：主题系统与数据刷新彻底解耦、交互层统一到 Pointer Events 状态机、箭头获得完整的编程化接口、plaintext 转换器实现无损往返、SSR 与移动端体验持续加固。对于集成方而言，理解refresh/changeTheme的职责边界、contextMenu.locale的迁移以及reshapeArrow与操作历史的联动，是升级到最新版本最关键的三个技术点。后续版本若继续演进，仓库 CHANGELOG.md 与 readme.md 是跟踪变更、核对 API 用法最可靠的第一手依据。