LogicFlow 渐进连线插件 ProximityConnect 完全指南拖拽智能吸附与虚拟边机制详解【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow渐进连线Proximity Connect是 LogicFlow 提供的一种动态交互能力通过在节点拖拽与锚点拖拽过程中动态计算距离并智能吸附帮助用户接近即可连省去精确对准锚点的繁琐操作。本文将以 proximity-connect.en.md 为骨架结合 插件源码 与 官方演示示例完整讲解其事件驱动原理、配置项、公开 API 与边界情况处理读完后你可以直接在项目中接入并深度定制该插件。渐进连线解决什么问题在传统流程图编辑器中将一个节点连向另一个节点往往要求鼠标精确对准目标节点的锚点Anchor否则连线不会命中。当画布节点密集、流程复杂时这种精确命中会显著拖慢设计效率。渐进连线插件通过动态交互 智能吸附来缓解这一问题拖拽过程中插件持续计算被拖拽对象与画布上其他节点锚点之间的距离一旦最近距离小于设定的阈值threshold就立即生成一条**虚拟边virtual edge**实时预览最终连线效果松手时再把虚拟边替换为真实边。用户只需要把节点或锚点拖到目标附近即可完成连接。该插件支持两种拖拽场景拖拽节点连线node 场景鼠标拖动整个节点移动时根据当前节点位置寻找距离最近的可连接锚点拖拽锚点连线anchor 场景鼠标从节点锚点拖出连线时根据鼠标当前所在位置寻找距离最近的可连接锚点。在 官方演示 中插件与一个基于 Ant Design 的控制面板组合使用可以实时调节连线阈值、连线方向、启用状态、工作模式以及虚拟边颜色与虚线样式是理解各配置项作用最直接的入口。事件驱动插件是如何工作的渐进连线完全由 LogicFlow 图模型的事件中心graphModel.eventCenter驱动。插件在render()阶段调用addEventListeners()注册监听核心事件与插件行为的对应关系如下表所示见文档事件插件行为node:dragstart将当前拖拽的节点数据存储到插件中node:drag1. 遍历画布上所有节点计算每个节点上每个锚点与当前拖拽节点上每个锚点的距离找出距离最短且可以连线的一组锚点存储下来2. 判断当前最短距离是否小于阈值若小于则创建一条虚拟边展示最终连线效果node:drop删除虚拟边创建真实边anchor:dragstart将当前拖拽的节点和触发锚点的数据存储到插件中anchor:drag1. 遍历画布上所有节点找出距离当前鼠标位置最短且可以连线的一个锚点存储到插件中2. 判断当前最短距离是否小于阈值若小于则创建一条虚拟边展示最终连线效果anchor:dragend删除虚拟边创建真实边对照 index.ts 可以确认这套监听注册逻辑每个事件回调首先检查enable与type模式匹配node模式跳过锚点事件、anchor模式跳过节点事件再进入各自的处理流程。这里有两个值得注意的过滤条件模式过滤this.type anchor时节点拖拽相关事件直接returnthis.type node时锚点拖拽相关事件直接return这正是配置项type控制工作模式的底层实现。启用开关!this.enable时所有拖拽事件不产生任何效果。两个核心搜索算法findClosestAnchorOfNode(draggingNode, allNodes)源码 L188-L228遍历画布上除自身外的所有节点对每个节点的每个锚点与拖拽节点的每个锚点做双重循环用twoPointDistance欧几里得距离实现在 packages/core/src/util/edge.ts计算点对距离持续记录最短的一对最终写入currentDistance、currentAnchor、closestAnchor、closestNode。findClosestAnchorOfAnchor(draggingPoint, allNodes)源码 L231-L263以鼠标在画布上的坐标点为基准遍历所有节点锚点找出与鼠标位置距离最近的可连接锚点。拖拽点坐标通过graphModel.getPointByClient({ clientX, clientY })从客户端坐标换算到画布覆盖层坐标。锚点可连接性校验anchorAllowConnect在记录最近锚点之前插件会调用anchorAllowConnect源码 L266-L282做双向校验这正是文档 Tip 2 中取锚点数据判断当前的一组锚点是否可连线的实现通过isAllowConnectedAsSource判断源节点是否允许作为起点通过isAllowConnectedAsTarget判断目标节点是否允许作为终点两个方法定义在 packages/core/src/model/node/BaseNodeModel.ts其内部会遍历节点上配置的sourceRules/targetRules连线规则逐条执行validate回调任何一条规则不通过isAllPass false即判定不可连线。这意味着渐进连线自动尊重你为节点配置的连接规则——即使距离再近规则不允许的锚点组合也不会生成虚拟边。reverseDirection为true时source/target 的角色会互换后重新校验。使用插件渐进连线插件随logicflow/extension扩展包发布入口导出见 packages/extension/src/index.ts。接入方式如下示例见文档import LogicFlow from logicflow/core; import { ProximityConnect } from logicflow/extension; import logicflow/core/es/index.css; import logicflow/extension/es/index.css; // 两种使用方式 // 方式一通过 use 方法注册插件 LogicFlow.use(ProximityConnect); // 方式二在实例化时通过 plugins 配置项启用可同时配置插件属性 const lf new LogicFlow({ container: document.querySelector(#app), plugins: [ProximityConnect], pluginsOptions: { proximityConnect: { // enable, // 插件是否启用 // distance, // 渐进连线阈值 // reverseDirection, // 连线方向 // type, // 插件工作模式default | node | anchor }, }, });注意pluginsOptions中插件的键名必须与插件静态属性pluginName一致。查看 index.ts 可知static pluginName proximityConnect因此配置项书写为proximityConnect。实例化后可通过lf.extension.proximityConnect拿到插件实例动态调用其公开 API官方演示中即采用这种方式与 UI 控件联动。配置项文档将插件全部可配置能力整理为下表字段类型默认值是否必须描述enablebooleantrue否是否启用插件distancenumber100否渐进连线阈值像素reverseDirectionbooleanfalse否是否创建反向连线。默认连线方向是当前拖拽的节点指向最近的节点设为true后变为最近的节点指向当前拖拽节点virtualEdgeStyleobject{ strokeDasharray: 10,10, stroke: #acacac }否虚拟边样式typestringdefault否插件工作模式default、node、anchor。default同时支持节点拖拽与锚点拖拽node仅在节点拖拽时生效anchor仅在锚点拖拽时生效各配置项在 ProximityConnectProps 类型 中有完整声明且在类构造函数中通过assign(this, options)直接合并为实例属性。配置项与源码字段的对应关系如下便于理解各自影响enable→ 实例字段enable默认true。所有事件回调入口的第一道闸门注意 setEnable(false) 的语义关闭插件的同时会调用resetData()清理当前缓存的最近节点/锚点与虚拟边。distance→ 实例字段thresholdDistance默认100。是currentDistance thresholdDistance比较中使用的像素阈值。需要说明的是字段名在源码中是thresholdDistance配置项键名为distance二者在构造函数中通过assign完成映射。reverseDirection→ 实例字段reverseDirection默认false。它同时影响anchorAllowConnect中 source/target 角色的互换以及addVirtualEdge中sourceNodeId/targetNodeId的排列。virtualEdgeStyle→ 实例字段virtualEdgeStyle。创建虚拟边时通过properties.style写入边属性源码 L350-L352。type→ 实例字段type默认default控制事件监听回调中的模式过滤。从源码结构看distance与thresholdDistance的键名差异属于历史命名使用时以文档表格中的键名为准即可。公开 API插件暴露了 4 个实例方法便于在运行时动态调整行为setThresholdDistance(distance)修改连线阈值setThresholdDistance (distance: number): void {}源码实现L408-L411会先用isFinite校验入参非有限数值直接忽略避免Infinity/NaN污染比较逻辑。setReverseDirection(reverse)修改创建连线的方向setReverseDirection (reverse: boolean): void {}setEnable(enable)设置插件启用状态setEnable (enable: boolean): void {}如上文所述传入false时除关闭功能外还会调用resetData()清理现场L419-L424。setVirtualEdgeStyle(style)设置虚拟边样式与已有样式做浅合并setVirtualEdgeStyle (style: Recordstring, unknown): void {}实现为this.virtualEdgeStyle { ...this.virtualEdgeStyle, ...value }L400-L405因此可以只传{ stroke: #ff0000 }单独覆盖颜色其余样式保留。官方演示 index.tsx 展示了这四个 API 的典型调用方式实例化后从lf.extension.proximityConnect取出插件实例将 UI 控件的当前状态同步到插件。虚拟边的创建、去重与落库虚拟边是渐进连线体验的核心其生命周期值得单独拆解对应addVirtualEdge源码 L315-L371真实边去重遍历graphModel.edges跳过edge.virtual true的边调用sameEdgeIsExist检查是否已存在同源、同目标、同源锚点、同目标锚点、同方向的真实边L285-L312。已存在则直接返回不重复创建——这是文档 Tip 1 与注意事项中去重逻辑的落地实现。虚拟边更新若当前已存在虚拟边先比较其端点信息与最新计算结果是否一致一致则保持不变避免拖拽过程中频繁重建不一致则deleteEdge删除旧边再创建新边。方向控制reverseDirection决定sourceNodeId/targetNodeId的排列——默认拖拽节点为 source、最近节点为 target反向则互换。标记虚拟性通过this.lf.addEdge(...)创建边后设置this.virtualEdge.virtual true打标这是后续去重时识别虚拟边的依据。在拖拽过程中handleNodeDragL125-L150与handleAnchorDragL159-L185还包含一道超阈值回收逻辑若虚拟边两端距离已经超过阈值立即删除虚拟边并置空引用防止连线预览拖尾残留。松手落库由handleDropL153-L156完成调用addActualEdge读取虚拟边的type、sourceNodeId、targetNodeId、sourceAnchorId、targetAnchorId、startPoint、endPoint、pointsList先删除虚拟边再用相同参数addEdge创建真实边L374-L397最后resetData()清理全部中间状态。边界情况与注意事项文档末尾明确了两条边界行为这里结合源码给出进一步解释去重逻辑画布上已存在同配置真实边同起止节点与锚点、同方向时插件不再创建虚拟边避免重复连线。注意去重比较同时包含reverseDirection分支方向不同的边互不干扰。锚点拖拽结束的特殊处理issue 2140锚点拖拽结束时若释放位置落在某个节点的锚点区域将不触发插件的连线创建以避免与内置锚点连线功能产生重复连线。相关实现在anchor:dragend回调中源码 L97-L121先通过getPointByClient换算释放点的画布坐标再调用核心工具函数isInNode实现在 packages/core/src/util/node.ts带 10px 容差判断释放点是否落在边目标节点的包围盒内若命中则删除虚拟边并直接return交给内置锚点连线逻辑处理。总结渐进连线插件把精确对准锚点这一高频低价值操作转化为拖到附近即可连的智能吸附体验。其设计要点可以概括为事件驱动、无侵入仅监听node:*与anchor:*六类拖拽事件不修改节点/边模型自身行为阈值吸附distancethresholdDistance决定吸附生效范围拖拽过程持续比对并回收超阈值的虚拟边尊重规则候选锚点对必须通过isAllowConnectedAsSource/isAllowConnectedAsTarget双向连接规则校验虚拟边生命周期创建 → 更新 → 超阈值回收 → 落库为真实边全程通过virtual标记与去重避免重复连线。若要继续深入建议阅读以下仓库文件插件完整实现 packages/extension/src/tools/proximity-connect/index.ts官方交互演示 sites/docs/src/tutorial/extension/proximity-connect/index.tsx距离计算工具 packages/core/src/util/edge.ts命中判断工具 packages/core/src/util/node.ts以及连接规则定义 packages/core/src/model/node/BaseNodeModel.ts。【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LogicFlow 渐进连线插件 ProximityConnect 完全指南：拖拽智能吸附与虚拟边机制详解
LogicFlow 渐进连线插件 ProximityConnect 完全指南拖拽智能吸附与虚拟边机制详解【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow渐进连线Proximity Connect是 LogicFlow 提供的一种动态交互能力通过在节点拖拽与锚点拖拽过程中动态计算距离并智能吸附帮助用户接近即可连省去精确对准锚点的繁琐操作。本文将以 proximity-connect.en.md 为骨架结合 插件源码 与 官方演示示例完整讲解其事件驱动原理、配置项、公开 API 与边界情况处理读完后你可以直接在项目中接入并深度定制该插件。渐进连线解决什么问题在传统流程图编辑器中将一个节点连向另一个节点往往要求鼠标精确对准目标节点的锚点Anchor否则连线不会命中。当画布节点密集、流程复杂时这种精确命中会显著拖慢设计效率。渐进连线插件通过动态交互 智能吸附来缓解这一问题拖拽过程中插件持续计算被拖拽对象与画布上其他节点锚点之间的距离一旦最近距离小于设定的阈值threshold就立即生成一条**虚拟边virtual edge**实时预览最终连线效果松手时再把虚拟边替换为真实边。用户只需要把节点或锚点拖到目标附近即可完成连接。该插件支持两种拖拽场景拖拽节点连线node 场景鼠标拖动整个节点移动时根据当前节点位置寻找距离最近的可连接锚点拖拽锚点连线anchor 场景鼠标从节点锚点拖出连线时根据鼠标当前所在位置寻找距离最近的可连接锚点。在 官方演示 中插件与一个基于 Ant Design 的控制面板组合使用可以实时调节连线阈值、连线方向、启用状态、工作模式以及虚拟边颜色与虚线样式是理解各配置项作用最直接的入口。事件驱动插件是如何工作的渐进连线完全由 LogicFlow 图模型的事件中心graphModel.eventCenter驱动。插件在render()阶段调用addEventListeners()注册监听核心事件与插件行为的对应关系如下表所示见文档事件插件行为node:dragstart将当前拖拽的节点数据存储到插件中node:drag1. 遍历画布上所有节点计算每个节点上每个锚点与当前拖拽节点上每个锚点的距离找出距离最短且可以连线的一组锚点存储下来2. 判断当前最短距离是否小于阈值若小于则创建一条虚拟边展示最终连线效果node:drop删除虚拟边创建真实边anchor:dragstart将当前拖拽的节点和触发锚点的数据存储到插件中anchor:drag1. 遍历画布上所有节点找出距离当前鼠标位置最短且可以连线的一个锚点存储到插件中2. 判断当前最短距离是否小于阈值若小于则创建一条虚拟边展示最终连线效果anchor:dragend删除虚拟边创建真实边对照 index.ts 可以确认这套监听注册逻辑每个事件回调首先检查enable与type模式匹配node模式跳过锚点事件、anchor模式跳过节点事件再进入各自的处理流程。这里有两个值得注意的过滤条件模式过滤this.type anchor时节点拖拽相关事件直接returnthis.type node时锚点拖拽相关事件直接return这正是配置项type控制工作模式的底层实现。启用开关!this.enable时所有拖拽事件不产生任何效果。两个核心搜索算法findClosestAnchorOfNode(draggingNode, allNodes)源码 L188-L228遍历画布上除自身外的所有节点对每个节点的每个锚点与拖拽节点的每个锚点做双重循环用twoPointDistance欧几里得距离实现在 packages/core/src/util/edge.ts计算点对距离持续记录最短的一对最终写入currentDistance、currentAnchor、closestAnchor、closestNode。findClosestAnchorOfAnchor(draggingPoint, allNodes)源码 L231-L263以鼠标在画布上的坐标点为基准遍历所有节点锚点找出与鼠标位置距离最近的可连接锚点。拖拽点坐标通过graphModel.getPointByClient({ clientX, clientY })从客户端坐标换算到画布覆盖层坐标。锚点可连接性校验anchorAllowConnect在记录最近锚点之前插件会调用anchorAllowConnect源码 L266-L282做双向校验这正是文档 Tip 2 中取锚点数据判断当前的一组锚点是否可连线的实现通过isAllowConnectedAsSource判断源节点是否允许作为起点通过isAllowConnectedAsTarget判断目标节点是否允许作为终点两个方法定义在 packages/core/src/model/node/BaseNodeModel.ts其内部会遍历节点上配置的sourceRules/targetRules连线规则逐条执行validate回调任何一条规则不通过isAllPass false即判定不可连线。这意味着渐进连线自动尊重你为节点配置的连接规则——即使距离再近规则不允许的锚点组合也不会生成虚拟边。reverseDirection为true时source/target 的角色会互换后重新校验。使用插件渐进连线插件随logicflow/extension扩展包发布入口导出见 packages/extension/src/index.ts。接入方式如下示例见文档import LogicFlow from logicflow/core; import { ProximityConnect } from logicflow/extension; import logicflow/core/es/index.css; import logicflow/extension/es/index.css; // 两种使用方式 // 方式一通过 use 方法注册插件 LogicFlow.use(ProximityConnect); // 方式二在实例化时通过 plugins 配置项启用可同时配置插件属性 const lf new LogicFlow({ container: document.querySelector(#app), plugins: [ProximityConnect], pluginsOptions: { proximityConnect: { // enable, // 插件是否启用 // distance, // 渐进连线阈值 // reverseDirection, // 连线方向 // type, // 插件工作模式default | node | anchor }, }, });注意pluginsOptions中插件的键名必须与插件静态属性pluginName一致。查看 index.ts 可知static pluginName proximityConnect因此配置项书写为proximityConnect。实例化后可通过lf.extension.proximityConnect拿到插件实例动态调用其公开 API官方演示中即采用这种方式与 UI 控件联动。配置项文档将插件全部可配置能力整理为下表字段类型默认值是否必须描述enablebooleantrue否是否启用插件distancenumber100否渐进连线阈值像素reverseDirectionbooleanfalse否是否创建反向连线。默认连线方向是当前拖拽的节点指向最近的节点设为true后变为最近的节点指向当前拖拽节点virtualEdgeStyleobject{ strokeDasharray: 10,10, stroke: #acacac }否虚拟边样式typestringdefault否插件工作模式default、node、anchor。default同时支持节点拖拽与锚点拖拽node仅在节点拖拽时生效anchor仅在锚点拖拽时生效各配置项在 ProximityConnectProps 类型 中有完整声明且在类构造函数中通过assign(this, options)直接合并为实例属性。配置项与源码字段的对应关系如下便于理解各自影响enable→ 实例字段enable默认true。所有事件回调入口的第一道闸门注意 setEnable(false) 的语义关闭插件的同时会调用resetData()清理当前缓存的最近节点/锚点与虚拟边。distance→ 实例字段thresholdDistance默认100。是currentDistance thresholdDistance比较中使用的像素阈值。需要说明的是字段名在源码中是thresholdDistance配置项键名为distance二者在构造函数中通过assign完成映射。reverseDirection→ 实例字段reverseDirection默认false。它同时影响anchorAllowConnect中 source/target 角色的互换以及addVirtualEdge中sourceNodeId/targetNodeId的排列。virtualEdgeStyle→ 实例字段virtualEdgeStyle。创建虚拟边时通过properties.style写入边属性源码 L350-L352。type→ 实例字段type默认default控制事件监听回调中的模式过滤。从源码结构看distance与thresholdDistance的键名差异属于历史命名使用时以文档表格中的键名为准即可。公开 API插件暴露了 4 个实例方法便于在运行时动态调整行为setThresholdDistance(distance)修改连线阈值setThresholdDistance (distance: number): void {}源码实现L408-L411会先用isFinite校验入参非有限数值直接忽略避免Infinity/NaN污染比较逻辑。setReverseDirection(reverse)修改创建连线的方向setReverseDirection (reverse: boolean): void {}setEnable(enable)设置插件启用状态setEnable (enable: boolean): void {}如上文所述传入false时除关闭功能外还会调用resetData()清理现场L419-L424。setVirtualEdgeStyle(style)设置虚拟边样式与已有样式做浅合并setVirtualEdgeStyle (style: Recordstring, unknown): void {}实现为this.virtualEdgeStyle { ...this.virtualEdgeStyle, ...value }L400-L405因此可以只传{ stroke: #ff0000 }单独覆盖颜色其余样式保留。官方演示 index.tsx 展示了这四个 API 的典型调用方式实例化后从lf.extension.proximityConnect取出插件实例将 UI 控件的当前状态同步到插件。虚拟边的创建、去重与落库虚拟边是渐进连线体验的核心其生命周期值得单独拆解对应addVirtualEdge源码 L315-L371真实边去重遍历graphModel.edges跳过edge.virtual true的边调用sameEdgeIsExist检查是否已存在同源、同目标、同源锚点、同目标锚点、同方向的真实边L285-L312。已存在则直接返回不重复创建——这是文档 Tip 1 与注意事项中去重逻辑的落地实现。虚拟边更新若当前已存在虚拟边先比较其端点信息与最新计算结果是否一致一致则保持不变避免拖拽过程中频繁重建不一致则deleteEdge删除旧边再创建新边。方向控制reverseDirection决定sourceNodeId/targetNodeId的排列——默认拖拽节点为 source、最近节点为 target反向则互换。标记虚拟性通过this.lf.addEdge(...)创建边后设置this.virtualEdge.virtual true打标这是后续去重时识别虚拟边的依据。在拖拽过程中handleNodeDragL125-L150与handleAnchorDragL159-L185还包含一道超阈值回收逻辑若虚拟边两端距离已经超过阈值立即删除虚拟边并置空引用防止连线预览拖尾残留。松手落库由handleDropL153-L156完成调用addActualEdge读取虚拟边的type、sourceNodeId、targetNodeId、sourceAnchorId、targetAnchorId、startPoint、endPoint、pointsList先删除虚拟边再用相同参数addEdge创建真实边L374-L397最后resetData()清理全部中间状态。边界情况与注意事项文档末尾明确了两条边界行为这里结合源码给出进一步解释去重逻辑画布上已存在同配置真实边同起止节点与锚点、同方向时插件不再创建虚拟边避免重复连线。注意去重比较同时包含reverseDirection分支方向不同的边互不干扰。锚点拖拽结束的特殊处理issue 2140锚点拖拽结束时若释放位置落在某个节点的锚点区域将不触发插件的连线创建以避免与内置锚点连线功能产生重复连线。相关实现在anchor:dragend回调中源码 L97-L121先通过getPointByClient换算释放点的画布坐标再调用核心工具函数isInNode实现在 packages/core/src/util/node.ts带 10px 容差判断释放点是否落在边目标节点的包围盒内若命中则删除虚拟边并直接return交给内置锚点连线逻辑处理。总结渐进连线插件把精确对准锚点这一高频低价值操作转化为拖到附近即可连的智能吸附体验。其设计要点可以概括为事件驱动、无侵入仅监听node:*与anchor:*六类拖拽事件不修改节点/边模型自身行为阈值吸附distancethresholdDistance决定吸附生效范围拖拽过程持续比对并回收超阈值的虚拟边尊重规则候选锚点对必须通过isAllowConnectedAsSource/isAllowConnectedAsTarget双向连接规则校验虚拟边生命周期创建 → 更新 → 超阈值回收 → 落库为真实边全程通过virtual标记与去重避免重复连线。若要继续深入建议阅读以下仓库文件插件完整实现 packages/extension/src/tools/proximity-connect/index.ts官方交互演示 sites/docs/src/tutorial/extension/proximity-connect/index.tsx距离计算工具 packages/core/src/util/edge.ts命中判断工具 packages/core/src/util/node.ts以及连接规则定义 packages/core/src/model/node/BaseNodeModel.ts。【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考