LogicFlow 2.0 升级指南：CDN 路径、插件配置与核心 API 变更全解析-二趣网

LogicFlow 2.0 升级指南：CDN 路径、插件配置与核心 API 变更全解析

【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架，支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow

导读

本指南系统梳理 LogicFlow 从 1.x 升级到 2.0 的全部变更要点，覆盖CDN 与包管理器引入路径调整、pluginsOptions配置结构变化（Breaking Change）、核心包 Node/Edge/Grid/Graph/Tool 的 API 重命名与新事件，以及框选、小地图、NodeResize、Snapshot、Group、HighLight、Label、Engine 等扩展模块的能力升级。读完本文，你将能一次性完成既有项目向 LogicFlow 2.0 的平滑迁移，并掌握 2.0 中"缩放/旋转能力内置"与"Label 文本模式"等新特性的正确用法。源码依据见 update.en.md 及仓库packages/core、packages/extension、packages/engine对应实现。

一、升级前必改的三处关键代码

2.0 对项目基础设施、核心功能与插件做了多模块优化并修复了一系列问题，其中有三处调整会直接影响现有代码能否正常运行，必须优先处理。

1. CDN 引入路径变更

1.x 时代核心包通过@logicflow/core/dist/logic-flow.js暴露 UMD 产物；2.0 起构建产物更名为dist/index.min.js，与 packages/core/package.json 中unpkg/jsdelivr字段指向的dist/index.min.js一致。

<!-- 原引入路径（1.x） --> <script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/logic-flow.js"></script> <link href="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/index.css" rel="stylesheet"> <script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/lib/Menu.js"></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/dist/index.css" /> <!-- 继续使用旧版本：在包名后追加版本号并保留旧路径 --> <script src="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/logic-flow.js"></script> <link href="https://cdn.jsdelivr.net/npm/@logicflow/core@1.2.27/dist/index.css" rel="stylesheet"> <script src="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/lib/Menu.js"></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension@1.2.27/dist/index.css" /> <!-- 直接引入 2.0 最新版 --> <script src="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/index.min.js"></script> <link href="https://cdn.jsdelivr.net/npm/@logicflow/core/dist/index.css" rel="stylesheet"> <script src="https://cdn.jsdelivr.net/npm/@logicflow/extension/dist/index.min.js"></script> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@logicflow/extension/dist/index.css" />

注意：若你的业务暂时无法升级但 CDN 未锁定版本，旧引入路径在 2.0 包下将失效，必须像上方第 2 段代码那样显式锁定@1.2.27版本号。

2. 包管理器引入样式路径变更

使用 npm/pnpm 等包管理器安装时，核心包样式的 ESM 入口从dist移到了es：

// 1.x 引入方式 import "@logicflow/core/dist/index.css"; // 2.0 引入方式 import "@logicflow/core/es/index.css";

这与 packages/core/package.json 中module: "es/index.js"、main: "lib/index.js"的产物划分相对应：es目录为面向打包器的 ES Module 产物，样式随之迁移。

3.`pluginsOptions`需按插件名拆分（Breaking Change）

这是 2.0 最重要的破坏性变更：1.x 中pluginsOptions直接透传所有数据给插件；2.0 起只接受与插件名称对应的 options 对象（详见 packages/core/src/options.ts 中pluginsOptions?: Record<string, any>的类型定义）。以小地图的showEdge配置为例：

// 1.x 写法：配置项平铺，可正常生效 new LogicFlow({ pluginsOptions: { showEdge, // MiniMap 可正常显示连线 }, }) // 2.0 写法：必须按插件名包裹 new LogicFlow({ pluginsOptions: { showEdge, // ❌ MiniMap 无法正常显示连线 MiniMap: { showEdge, // ✅ MiniMap 可正常显示连线 }, }, })

同样地，框选插件的exclusiveMode也需按此规则传递——其构造函数正是从options?.exclusiveMode读取该配置（见 selection-select/index.ts）。

二、项目基础设施优化

2.0 在工程层面做了四项结构性调整，对使用方是透明的，但解释了为什么产物与依赖发生了变化：

补充了项目内所有组件与方法的类型定义，@logicflow/core的types指向lib/index.d.ts，TS 用户的补全与类型检查更完整；
核心包渲染层preact切换为preact/compat，从 packages/core/package.json 的preact: ^10.17.1与源码import { createElement as h } from 'preact/compat'（见 options.ts）可确认；
移除dependencies中的 jest 依赖，lodash替换为lodash-es，核心包运行时依赖更轻（当前仅剩lodash-es、classnames、mobx、mobx-preact、mobx-utils、mousetrap、preact、uuid）；
完善了 README.md 与 CONTRIBUTING 相关文档。

三、核心包（Core）变更详解

1. Node：新增事件、方法重命名与文本样式

新增能力——三个节点事件（常量定义见 constant/index.ts，参数类型见 event/eventArgs.ts）：

node:resize：节点缩放，回调携带preData、data、model、deltaX、deltaY、index；
node:rotate：节点旋转，回调携带data、e、model；
node:properties-change：节点properties变化，回调携带id、改变的keys、preProperties与变更后的properties。该事件由BaseNodeModel.updateProperties在写入properties后通过graphModel.eventCenter.emit触发（见 BaseNodeModel.ts）。

方法重命名（Shape 组件重构）：升级时请全局检索并替换以下旧名称：

1.x 旧名称	2.0 新名称
`formateAnchorConnectValidateData`	`formatAnchorConnectValidateData`
`setHoverON`	`setHoverOn`
`setHoverOFF`	`setHoverOff`

其中formatAnchorConnectValidateData在 2.0 中用于将边校验结果统一格式化为{ isAllPass, msg }结构（实现见 util/node.ts），并已从 core 入口对外导出。

其他 Node 优化：

移除TextNode的getBackground中rectAttr下y: y-1的设置；
fakerNode重命名为fakeNode；
节点文本样式支持通过properties.textStyle配置：BaseNodeModel.getTextStyle()会先取主题nodeText，再用properties.textStyle逐项覆盖（见 BaseNodeModel.ts），因此现在可以针对单个节点覆盖文本样式。

Bug 修复：多边形在points设置原点、并按设置的宽高缩放后，形状与边框定位异常的问题已解决。

2. Edge：分段调整起点终点与文本样式

新增能力：

新增adjustEdgeStart与adjustEdgeEnd，可单独调整边的起点或终点。二者与adjustEdgeStartAndEnd一样是EditConfigModel的可观察配置项，默认均为false（见 EditConfigModel.ts），且当设置了adjustEdgeStartAndEnd: true时会自动同步开启adjustEdgeStart与adjustEdgeEnd（见 EditConfigModel.ts）；
边文本样式支持通过properties.textStyle配置，对应BaseEdgeModel.getTextStyle()对主题edgeText的读取（见 BaseEdgeModel.ts）。

Bug 修复：修复初始化时edgeConfig未传type时，graphModel.edgeType（默认边类型）未用于初始化边的问题。

3. Grid：自初始化与点阵网格修正

Grid类自行实现网格配置项的初始化，不再依赖外部赋值；
修改点状网格中"点"的最大半径计算逻辑并补充相关注释；
修正原网格中offset的偏移问题；
修正网格配置项的类型声明。

4. Graph：画布尺寸与滚动问题

优化初始化时画布尺寸的设置逻辑：窗口调整时可同步更新画布大小；
Breaking Change：pluginsOptions只传入插件对应的 options 数据（即第一节第 3 点）；
修复stopMoveGraph: true但未设置stopScrollGraph: true时画布无法滚动的问题；
修复GraphModel.getAreaElement方法的 bug。

5. Tool：TextEditTool 修复

1.x 中TextEditTool失效的根本原因是：组件更新时，原始的graphModel与LogicFlowprops 不会触发组件更新，2.0 改为通过传入textEditElement触发组件更新；同时移除了代码中无用的 console 输出、将@babel/plugin-proposal-class-properties更新为@babel/plugin-transform-class-properties，并将EventArgs相关类型由unknown改为any。

四、扩展（Extension）变更详解

1. 框选插件（Selection Select）

新增selection:selected-area事件，用于返回框选范围（由 selection-select/index.ts 通过this.lf.emit('selection:selected-area', ...)触发）；
默认启用状态改为禁用：源码中private disabled = true（见 selection-select/index.ts）。如需初始化即启用，必须在实例创建后调用lf.extension.selectionSelect.open()（该方法将disabled置为false，见同文件 L378-L383）。插件还挂载了lf.openSelectionSelect/lf.closeSelectionSelect/lf.setSelectionSelectMode三个便捷方法；
修复启用框选后页面滚动事件被阻止的问题，以及缩放后框选边距与外边框宽度计算错误的问题。

2. 小地图插件（MiniMap）

新增能力：

支持配置显示位置：updatePosition方法接受'left-top' | 'right-top' | 'left-bottom' | 'right-bottom'预设，或包含left/right/top/bottom的对象（见 mini-map/index.ts）；
支持选择是否渲染连线：可在初始化时通过showEdge配置（源码默认showEdge = false），也可通过实例方法setShowEdge(showEdge: boolean)动态更新（见 mini-map/index.ts）；
优化显示内容：由画布元素与视口位置共同决定小地图展示区域；
优化小地图预览的拖拽交互体验；
新增关闭回调事件miniMap:close：在hide()时触发（见 mini-map/index.ts）。

问题修复：优化画布移动时小地图的更新策略以降低性能消耗；修复点击小地图预览窗口引发画布意外移动的问题；修复小地图预览窗口无法拖拽的问题。

3. NodeResize：缩放/旋转能力内置

这是 2.0 的一个里程碑式变化：1.x 需要引入 NodeResize 插件才能缩放节点，2.0 将缩放能力内置到基础节点，并同时支持可配置的节点旋转。相关配置：

全局配置：实例初始化时通过allowResize与allowRotate控制当前实例下所有节点是否可缩放/可旋转（类型定义见 options.ts）；
单节点配置：在初始渲染数据的properties中加入resizable/rotatable字段控制单个节点（仅在全局allowResize/allowRotate为true时生效）。BaseNodeModel内部resizable与rotatable默认均为true（见 BaseNodeModel.ts），并提供了setResizable/setRotatable方法运行时修改（见 BaseNodeModel.ts）；
统一 NodeResize 中getResizeOutlineStyle的fill与stroke返回值。

提示：缩放能力内置后，NodeResize 插件将逐步弃用。

Bug 修复：解决缩放结束后节点重新定位的问题；修复HtmlResize节点outlineStyle的fill默认为黑色的问题。

4. Snapshot 快照插件

优化 bpmn 插件的导出内容；
导出节点时支持网络图片；
完善快照用法：支持自定义导出文件名、文件类型、图片宽高、背景色、图片质量等属性；
修复开启本地渲染后导出内容缺失的问题。

5. Group 插件升级为 Dynamic Group

2.0 重写了 group 插件的逻辑，并将其升级为 Dynamic Group 插件：

新增能力：支持组合节点的同步缩放与旋转，内部元素随之同步缩放/旋转；
优化：ResizeControl的尺寸范围由 30 缩减为 15，避免遮挡 Group 折叠小按钮；优化允许文本拖拽的逻辑判断为nodeTextDraggable && draggable同时满足时才允许拖拽。

6. HighLight 高亮插件

支持高亮邻居节点模式；
支持通过外部参数配置高亮形式；
补充了功能文档 HighLight 插件。

7. 「新增」Label 插件

2.0 新增了全新的文本展示格式Label，与既有 Text 格式的核心差异：

支持为节点/边添加多个文本，并可设置文本方向；
自带富文本编辑能力，支持设置局部文本样式；
采用新的位置计算算法，调整节点与边时优化关联文本的移动体验。

功能入口详见 Label 插件文档。

文本模块配套优化：

优化文本可编辑配置项的赋值优先级：textEdit（全局）>nodeTextEdit/edgeTextEdit（分类）> 元素自身可编辑性；
为graphModel增加textMode属性以标识当前文本模式（Options.Common中可见textMode/edgeTextMode/nodeTextMode三个配置，见 options.ts）；
在BaseNodeModel、BaseEdgeModel与graphModel中新增updateTextMode方法；
为文本模块新增可监听事件。

五、Engine 引擎变更

@logicflow/engine在 2.0 中做了两处关键改造：

重构引擎模块代码，使用 sandbox 替代频繁的 iframe 追加：1.x 的浏览器端实现通过反复创建隐藏 iframe 并注入全局数据来执行代码片段（该实现仍以注释形式保留在 browserVm.ts），频繁追加 iframe 会带来明显的性能开销；2.0 改为使用@nyariv/sandboxjs，编译代码后在其沙箱中执行（见 browserVm.ts）；
浏览器端与 Node 端执行保持一致：浏览器默认通过上述沙箱执行代码，Node 端同样使用@nyariv/sandboxjs执行代码片段（见 platform/node/index.ts 对runInNodeContext的引用），保证两端行为一致。

六、升级核对清单

完成升级后，建议按以下清单逐项验证：

CDN 路径已切换为dist/index.min.js，或旧版本显式锁定@1.2.27；
包管理器样式引入已改为@logicflow/core/es/index.css；
所有pluginsOptions已按插件名（如MiniMap、SelectionSelect）拆分包裹；
formateAnchorConnectValidateData/setHoverON/setHoverOFF等旧方法名已全局替换；
fakerNode已替换为fakeNode；
使用框选插件时，已在实例创建后调用lf.extension.selectionSelect.open()（若需默认启用）；
缩放/旋转改为使用全局allowResize/allowRotate与节点properties.resizable/rotatable；
Group 相关能力已按 Dynamic Group 插件的新用法迁移。

结语

LogicFlow 2.0 的核心升级思路清晰：对外收紧配置契约（pluginsOptions按插件名隔离）、对内重构基础设施（preact/compat、lodash-es、类型补全），同时把高频能力（缩放、旋转、文本样式、Label 多文本）从插件下沉或升级到核心与新一代插件中。对于存量项目，只需对照本指南的前三节完成迁移动作，即可平滑升级并立即享受到新事件、新文本模式与更低开销的引擎执行能力。更多细节可继续阅读升级中文版文档及仓库中对应模块的源码与测试用例。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析