LogicFlow 内置插件类型体系Extension、Label、Menu 与 Layout 的类型全解析【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow本篇文章系统梳理 LogicFlow 内置插件Built-in plugin相关的全部类型定义涵盖插件实例契约Extension、类式与对象式两种插件形态ExtensionConstructor/ExtensionDefinition、插件注册配置ExtensionConfig、构造参数IExtensionProps以及Label、Menu两款常用插件的专属类型。文中所有类型均以当前仓库 类型字典目录 为骨架并结合 插件安装机制源码 与logicflow/extension、logicflow/layout的实际实现帮助读者既能在 TypeScript 中正确使用这些类型也能理解插件被安装、实例化与销毁的底层流程。插件类型总览LogicFlow 的插件官方文档中统称 Extension相关类型全部集中在核心包的类型字典中。官方 API 文档通过 plugin-types.en.md 这一索引页汇总了它们具体完整定义位于 MainTypes.en.md 的「Plugin-related types」章节。类型说明Extension插件实例契约instance contractExtensionRenderFunc插件渲染函数签名render hookExtensionType插件联合类型unionExtensionConfig插件注册配置结构IExtensionProps插件构造参数constructor propsExtensionConstructor类式插件class-based pluginExtensionDefinition对象式插件object-style pluginLabelConfigLabel 插件的数据类型LabelOptionLabel 插件的全局配置项MenuConfig右键菜单context menu条目定义Layout 自动布局logicflow/layout的 Dagre / ElkLayout 及分组布局 API这些类型并非孤立存在它们与实例初始化选项中的plugins、pluginsOptions、disabledPlugins直接关联共同构成从「注册插件」到「插件运行」的完整类型链路。下面逐一展开。插件实例契约Extension 与 ExtensionRenderFuncExtension描述的是一个插件实例在安装完成后必须提供的运行时接口字段类型说明render(lf: LogicFlow, container: HTMLElement) void将插件 UI 挂载到插件容器中destroy() void可选清理钩子cleanup hook对应的渲染函数独立抽取为ExtensionRenderFunc类型export type ExtensionRenderFunc (lf: LogicFlow, container: HTMLElement) void从源码看render的调用时机在插件实例化之后。在 packages/core/src/LogicFlow.tsx 的installPlugin内部实例化完成的插件会把extensionIns.render以bind(extensionIns)的方式 push 进this.components随后由渲染管线在插件容器中执行。这意味着插件可以在 render 阶段拿到宿主实例lf与容器 DOM从而注册自定义的浮层、工具或快捷键。destroy则在lf.destroy()时被遍历调用用于释放事件监听、移除浮层等资源见同一文件中destroy()方法对this.extension的清理逻辑。因此凡是用class或对象形式实现了这两个成员的插件都会被核心运行时正确托管生命周期。插件的两种形态类式与对象式插件在注册时可以是联合类型ExtensionType ExtensionConstructor | ExtensionDefinition中的任意一种。类式插件 ExtensionConstructorexport interface ExtensionConstructor { pluginName: string new (props: IExtensionProps): Extension }类式插件以「类」的形式声明类上必须有静态属性pluginName用于唯一标识、去重与按名禁用构造函数接收IExtensionProps实例必须满足Extension契约。例如logicflow/extension中的 Label 插件export class Label implements Extension { static pluginName label constructor({ lf, options }: { lf: LogicFlow; options: ILabelOptions }) { // ... } }对应的实际声明位于 packages/extension/src/tools/label/index.ts。对象式插件 ExtensionDefinitionexport type ExtensionDefinition { pluginName: string install?: (lf: LogicFlow, LFCtor: LogicFlowConstructor) void render?: ExtensionRenderFunc }对象式插件不需要new而是直接提供pluginName与可选的install/render钩子install(lf, LFCtor)安装阶段同步调用适合注册自定义事件、改写实例方法或扩展lf的 APIrender(lf, container)与类式插件的render语义一致。运行时如何区分两种形态源码中的installPlugin通过特性检测duck-typing区分两种插件if (pluginName in extension install in extension) { // 对象式调用 install并把 render 注册进组件队列 install install.call(extension, this, LogicFlow) render this.components.push(render.bind(extension)) this.extension[pluginName] extension } else { // 类式new 实例化并把 render 注册进组件队列 const ExtensionCtor extension as ExtensionConstructor const extensionIns new ExtensionCtor({ lf: this, LogicFlow, props, options }) this.extension[pluginName] extensionIns }这段逻辑位于 packages/core/src/LogicFlow.tsx#L1411-L1438。可以看到无论哪种形态安装后的插件都会被存入this.extension[pluginName]这也是官方约定通过lf.extension.pluginName调用插件 API 的由来。两种形态对调用方是透明的——用户只需在plugins数组中传入类或对象即可。注册配置与构造参数ExtensionConfig、IExtensionPropsExtensionConfig当插件需要携带注册参数时可通过ExtensionConfig包裹export type ExtensionConfig { [pluginFlag]: symbol extension: ExtensionType props?: Recordstring, any }其中pluginFlag是核心内部用于标记「已包装插件」的唯一 Symbol源码中定义为Symbol(plugin registered by Logicflow.use)。installPlugins在遍历插件列表时会先检查pluginFlag in ext若命中则从中取出extension与props再安装否则按裸插件处理。因此在plugins: [MyPlugin, { extension: OtherPlugin, props: {...} }]这种混用写法下props会被正确透传给类式插件的构造函数。IExtensionProps类式插件构造函数收到的参数结构为字段类型说明lfLogicFlow宿主实例LogicFlowLogicFlowConstructor构造函数引用供高级用法如动态注册使用propsRecordstring, unknown可选注册时通过ExtensionConfig.props传入的自定义参数optionsRecordstring, unknown插件专属配置项其中options的来源值得注意核心从全局初始化参数pluginsOptions[pluginName]中取出对应当前插件的配置并注入即初始化时pluginsOptions: { label: { isMultiple: false } }这样的写法最终会以options形式进入插件构造函数。这一点在 LogicFlow.tsx 的installPlugin中通过this.options.pluginsOptions?.[pluginName] ?? {}实现。通过 pluginsOptions 与 disabledPlugins 控制插件plugins与pluginsOptions、disabledPlugins共同出现在实例初始化选项Common中plugins?: ExtensionType[] // 启用的插件列表 pluginsOptions?: Recordstring, any // 各插件专属配置以 pluginName 为 key disabledPlugins?: string[] // 按 pluginName 禁用的插件禁用逻辑同样在installPlugins中安装前会比对disabledPlugins命中则跳过安装见 packages/core/src/LogicFlow.tsx#L1382-L1406。这种设计让插件既可以全局静态注册plugins也可以按业务场景动态裁剪disabledPlugins而无需修改插件源码。Label 插件类型LabelConfig 与 LabelOptionLabel是logicflow/extension提供的文本标签插件用于在节点上渲染一个或多个独立 Label。其相关类型定义如下。LabelConfig单条 Label 的数据字段类型说明idstring可选Label 唯一标识typestring可选类型标记x/ynumber画布坐标contentstring可选富文本内容valuestring纯文本内容rotatenumber可选旋转角度styleh.JSX.CSSProperties可选Label 自定义样式editable/draggableboolean可选是否可编辑 / 可拖拽labelWidthnumber可选Label 宽度textOverflowModeellipsis \| wrap \| clip \| nowrap \| default可选文本溢出处理方式verticalboolean可选是否渲染纵向文本LabelConfig实际声明位于 packages/core/src/LogicFlow.tsx#L1535-L1554。在运行时_label数据支持三种形态string、LabelConfig、LabelConfig[]插件内部会统一归一化为LabelConfig[]再渲染见 packages/extension/src/tools/label/index.ts 的formatConfig逻辑。LabelOption插件全局配置字段类型说明isVerticalboolean节点所有 Label 是否纵向展示isMultipleboolean是否支持多个 LabelmaxCountnumber可选允许的 Label 最大个数除官方类型字典中的这三个字段外logicflow/extension的 Label 插件还接受labelWidth与textOverflowMode两个附加选项见 packages/extension/src/tools/label/index.ts#L26-L31并提供了默认值isMultiple默认true、maxCount默认Infinity、textOverflowMode默认default。启用该插件时构造器还会把画布的textMode切换到LABEL模式并注册LabelOverlay工具、禁用与其互斥的text-edit-tool这些细节体现了插件与核心编辑配置模型的联动。Menu 插件类型MenuConfigMenuConfig是logicflow/extension中右键菜单context-menu插件使用的类型按元素维度拆分为四类菜单export type MenuConfig { nodeMenu?: MenuItem[] | false edgeMenu?: MenuItem[] | false graphMenu?: MenuItem[] | false selectionMenu?: MenuItem[] | false }每条MenuItem的定义见 packages/extension/src/components/menu/index.ts#L10-L16字段类型说明textstring可选菜单项文案classNamestring可选自定义类名iconboolean \| string可选图标布尔开关或图标标识disabledboolean可选是否禁用callback(element: any) void点击回调参数为命中的元素插件安装后会在lf上挂载setMenuConfig/addMenuConfig/getMenuConfig/resetMenuConfigByType等 API见 menu/index.ts#L68-L84其中set为整体替换、add为追加合并二者都会自动刷新当前菜单。将nodeMenu等置为false可以关闭对应类别的菜单。Layout 插件自动布局的 API 与类型logicflow/layout包提供 Dagre 与 ElkLayout 两种自动布局插件其插件名分别为dagre与elkLayout。安装后即可通过lf.extension.dagre.layout(...)或lf.extension.elkLayout.layout(...)调用。完整参数表见 sites/docs/docs/api/extension/layout.en.md核心要点如下。Dagre 同步布局的常用选项选项类型默认值说明rankdirLR \| TB \| BT \| RLLR布局方向alignUL \| UR \| DL \| DRUL节点对齐方式nodesepnumber100同层节点间距ranksepnumber150层间距marginx/marginynumber120水平 / 垂直外边距rankernetwork-simplex \| tight-tree \| longest-pathtight-tree分层策略isDefaultAnchorbooleanfalse为true时重算折线路径与默认锚点分组布局选项Dagre 与 ElkLayout 共用选项类型默认值说明groupIdstring—省略则整图布局指定则仅布局其直接 children 与内部边resizeGroupfalse \| grow-only \| fitfalse是否在布局后调整 group 尺寸groupPaddingnumber40子元素边界之外的留白其中resizeGroup的三种模式语义明确false保持 group 尺寸并仅打印溢出告警grow-only只扩张以包裹子元素与 paddingfit按子元素自适应缩放可放大可缩小。resizeGroup: false是 pool / lane 的默认选择以保持泳道结构不被破坏嵌套 group 会按「最深优先」顺序处理。布局包架构细节可继续阅读 packages/layout/ARCHITECTURE.md。扩展类型BPMN 辅助类型除了插件机制本身类型字典中还包含一组 BPMN 元素扩展用的辅助类型供bpmn-elements预设使用DefinitionConfigType{ nodes: string[]; definition: EventDefinitionType[] | TaskDefinitionType[] }把 BPMN 定义绑定到一批元素类型上DefinitionPropertiesType{ definitionType: string; [key: string]: any }BPMN XML 的判别字段与扩展序列化字段EventDefinitionType事件定义含type、icon、toJSON序列化钩子与properties默认属性TaskDefinitionType任务定义以type标识任务并保留扩展槽位。这些类型让 BPMN 事件的type命名与 BPMN XML 保持一致同时通过toJSON与properties实现「XML → 节点属性 → XML」的双向序列化闭环。插件安装的完整调用链综合源码一个插件从注册到销毁的完整链路可以概括为注册初始化参数plugins中的插件含ExtensionConfig包裹形式与通过LogicFlow.use全局注册的插件被合并过滤installPlugins先解包pluginFlag标记的配置再按pluginName与disabledPlugins做排除packages/core/src/LogicFlow.tsx#L1382-L1406安装对象式插件走install钩子类式插件走new ExtensionCtor(props)两者均注入IExtensionProps并把render挂入组件队列、把实例存入lf.extension[pluginName]packages/core/src/LogicFlow.tsx#L1411-L1438渲染与销毁渲染阶段执行render(lf, container)lf.destroy()时逐个调用插件实例的destroy()清理资源。这条链路解释了类型设计背后的动机ExtensionType联合类型让两种插件形态在类型层面收敛ExtensionConfig为插件携带props提供入口IExtensionProps统一了类式插件的构造参数而Extension契约保证了运行时对渲染与销毁的统一调度。小结本文围绕 LogicFlow 内置插件类型体系展开从Extension/ExtensionRenderFunc的运行时契约到ExtensionConstructor/ExtensionDefinition两种插件形态及其在核心源码中的区分逻辑再到ExtensionConfig/IExtensionProps的注册与参数注入机制最后覆盖LabelConfig/LabelOption、MenuConfig与logicflow/layout布局 API 的具体类型与默认值。掌握了这些类型读者既可以写出类型安全的自定义插件也能借助pluginsOptions与disabledPlugins精细控制内置插件行为并进一步阅读 MainTypes.en.md 与 插件开发相关文档 获取完整定义。【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考