LogicFlow 渲染与数据读写指南render / getGraphData / clearData 与 adapter 适配机制详解【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow本篇技术指南围绕 LogicFlow 实例的渲染入口与数据读写 API 展开涵盖render、renderRawData、getGraphData、getGraphRawData、clearData以及adapterIn/adapterOut双适配器钩子。通过阅读本文你将掌握如何将外部业务数据如 BPMN JSON、自研 DSL接入 LogicFlow 画布、如何取出被适配后的数据以及如何基于适配器机制构建与业务数据结构解耦的通用图编辑能力。一、总体概览渲染与数据的两个通道LogicFlow 实例LogicFlow类在数据层面刻意设计了两条通道原生通道Native直接使用 LogicFlow 内部定义的GraphData结构{ nodes, edges }不经过任何转换。对应renderRawData与getGraphRawData。适配通道Adapted先经过adapterIn将业务数据转换为内部结构再渲染或在导出时经过adapterOut将内部结构转换为业务结构。对应render与getGraphData。这一设计使得 LogicFlow 既能作为开箱即用的流程图框架也能无缝嵌入已有业务系统——业务方只需要维护一套数据映射函数而不必改造画布内部模型。相关的核心类型定义位于 packages/core/src/LogicFlow.tsx完整类型字典可参考 sites/docs/docs/api/type/MainTypes.en.md。二、渲染入口render 与 renderRawData2.1 render经过 adapterIn 的渲染入口签名render(graphData: unknown): void参数名称类型必填说明graphDataunknown是图数据载荷具体结构取决于adapterIn的约定。示例lf.render({ nodes: [{ id: node_1, type: rect, x: 120, y: 100 }], edges: [], });从源码实现看render的调用链非常清晰packages/core/src/LogicFlow.tsxrender(graphData: GraphConfigData) { let graphRawData cloneDeep(graphData) if (this.adapterIn) { graphRawData this.adapterIn(graphRawData) } this.renderRawData(graphRawData) }几点值得注意的实现细节先cloneDeep再转换传入的graphData会被深拷贝避免适配过程中意外修改调用方持有的原始对象。adapterIn可选未配置adapterIn时render等价于直接调用renderRawData此时graphData必须是原生GraphConfigData结构。并非增量更新render会重建整个画布模型见下文renderRawData用于初始化或整体替换图数据而不是在现有画布上追加节点。2.2 renderRawData免适配的原生渲染签名renderRawData(graphData: GraphData): void参数名称类型必填说明graphDataGraphData是LogicFlow 原生图数据{ nodes, edges }。示例lf.renderRawData({ nodes: [{ id: node_1, type: rect, x: 120, y: 100 }], edges: [], });renderRawData是真正的底层渲染实现packages/core/src/LogicFlow.tsxrenderRawData(graphRawData: GraphConfigData) { this.graphModel.graphDataToModel(formatData(graphRawData)) if (this.options.history ! false) { this.history.watch(this.graphModel) } render( Graph getView{this.getView} tool{this.tool} options{this.options} dnd{this.dnd} snaplineModel{this.snaplineModel} graphModel{this.graphModel} /, this.container, ) this.emit(EventType.GRAPH_RENDERED, { data: this.graphModel.modelToGraphData(), graphModel: this.graphModel, }) }调用链说明formatData(graphRawData)对输入数据做兼容性归一化兼容 Vue 等响应式包装的数据graphDataToModel将配置数据转换为内部 Model见 packages/core/src/model/GraphModel.ts。转换过程中每个节点会经过getModelAfterSnapToGrid吸附到网格边则通过getModel(edge.type ?? currEdgeType)找到注册的边模型若类型未注册会抛出找不到${edge.type}对应的边。错误——这意味着renderRawData要求所有用到的节点/边类型都已被register注册历史记录绑定当实例选项history不为false时为graphModel启动历史监听从而支持undo/redo渲染 Graph 根组件将Graph视图挂载到实例容器此时节点、边、文本真正出现在画布上派发GRAPH_RENDERED事件渲染完成后触发回调中携带data当前画布数据的快照与graphModel可在渲染完成后立即拿到最新模型做后续处理。因此建议通用插件内部一律使用renderRawData而非render以避免适配器干扰插件对数据结构的假设。三、数据导出getGraphData 与 getGraphRawData3.1 getGraphData可携带额外参数的导出签名getGraphData(...params: any[]): GraphConfigData | unknown参数名称类型必填说明...paramsany[]否透传给adapterOut的额外参数。返回值未配置adapterOut返回GraphConfigData原生结构配置了adapterOut返回你的业务结构unknown。示例const data lf.getGraphData([property1, property2]);源码实现packages/core/src/LogicFlow.tsx表明getGraphData内部先取原生数据再交给adapterOutgetGraphData(...params: any): GraphData | unknown { const data this.getGraphRawData() if (this.adapterOut) { return this.adapterOut(data, ...params) } return data }其中...params被原样透传这使得业务侧可以在调用导出时动态传入额外信息例如是否包含坐标、需要保留的业务字段名等由adapterOut决定如何使用。3.2 getGraphRawData免适配的原生导出签名getGraphRawData(): GraphData返回值GraphData{ nodes: NodeData[], edges: EdgeData[] }。示例const rawData lf.getGraphRawData(); console.log(rawData.nodes, rawData.edges);实现为一行packages/core/src/LogicFlow.tsxgetGraphRawData(): GraphData { return this.graphModel.modelToGraphData() }modelToGraphDatapackages/core/src/model/GraphModel.ts遍历内部edges与nodes逐个调用getData()收集数据并过滤掉virtual标记的元素——这保证了诸如拖拽预览、临时连线等虚拟元素不会泄漏进导出的数据。3.3 官方注释给出的选型建议源码中对getGraphData的注释packages/core/src/LogicFlow.tsx明确提示getGraphData 返回的数据受到 adapter 影响所以其数据格式不一定是 logicflow 内部图数据格式。如果实现通用插件请使用 getGraphRawData。这是插件开发者的重要约定依赖内部结构的代码如快照、布局、校验插件必须走getGraphRawData/renderRawData原生通道只有面向业务输出/输入时才使用适配通道。四、清空画布clearData签名clearData(): void示例lf.clearData();clearData的实现packages/core/src/LogicFlow.tsxclearData() { this.graphModel.clearData() // 强制刷新数据, 让 preact 清除对已删除节点的引用 this.render({}) }模型层的clearDatapackages/core/src/model/GraphModel.ts会清空nodes、edges并同步清理edgeModelMap、nodeModelMap、elementsModelMap三张索引表防止内存中残留对已删除元素的引用。随后render({})触发一次空数据渲染让视图层彻底释放对被删除节点的引用。需要区分两个概念clearData()清空画布上的所有节点与边元素级清空画布实例本身保留lf.destroy()销毁整个实例与容器见 packages/core/src/LogicFlow.tsx适用于页面卸载场景。五、适配器钩子adapterIn 与 adapterOut适配器是 LogicFlow 与业务数据格式解耦的核心机制。两者均为实例上的可选属性直接赋值即可生效。5.1 adapterIn入站适配签名adapterIn?: (data: unknown) GraphData返回值GraphData转换为 LogicFlow 原生图数据。示例lf.adapterIn (bizData) { return { nodes: [], edges: [], }; };典型用法业务后端返回的数据结构例如字段名为processNodes/processEdges坐标字段为cx/cy与 LogicFlow 的NodeConfig/EdgeConfig不一致时在adapterIn中做字段映射、坐标换算如中心点坐标系、左上角坐标系互转以及数据清洗保证render收到的永远是干净的内部结构。5.2 adapterOut出站适配签名adapterOut?: (data: GraphConfigData, ...params: any[]) unknown参数名称类型必填说明dataGraphConfigData是当前画布的原生图数据。...paramsany[]否与getGraphData传入的额外参数一致。示例lf.adapterOut (data, reserveFields []) { return { processNodes: data.nodes, processEdges: data.edges, reserveFields, }; };典型用法将内部{ nodes, edges }转换为业务侧的协议结构同时利用...params支持本次导出是否包含布局信息需要保留的字段白名单等调用期动态选项。getGraphData在adapterOut存在时返回unknown即业务结构不存在时退化为返回GraphConfigData。5.3 真实案例BPMN 适配器adapterIn/adapterOut并非纸面概念LogicFlow 官方扩展中的 BPMN 适配器就是完整实践packages/extension/src/bpmn-adapter/index.ts。其目录注释packages/extension/src/bpmn-adapter/index.ts点明了双向职责adapterOut将 LogicFlow 图数据转换为 BPMN JSON随后由json2xml转为 XMLadapterIn将 BPMN JSON 转换为 LogicFlow 图数据如果是 XML则先经xml2json转为 JSON。在BpmnAdapter中适配器被注入到实例上packages/extension/src/bpmn-adapter/index.tslf.adapterIn (data) this.adapterIn(data) lf.adapterOut (data, retainedFields?: string[]) this.adapterOut(data, retainedFields)坐标换算的细节也印证了适配器存在的必要性packages/extension/src/bpmn-adapter/index.tsbpmn坐标是基于左上角LogicFlow基于中心点此处处理一下。此外还提供BpmnXmlAdapter变体packages/extension/src/bpmn-adapter/index.ts将adapterIn/adapterOut替换为面向 XML 的adapterXmlIn/adapterXmlOut——内部先调xml2json再复用基础适配逻辑见 packages/extension/src/bpmn-adapter/index.ts。这展示了适配器可以叠加管道XML → JSON → GraphData逐层解耦。六、数据类型速查渲染与数据 API 依赖的核心类型定义如下源码位于 packages/core/src/LogicFlow.tsx详细字段说明见 sites/docs/docs/api/type/MainTypes.en.md。GraphConfigData 与 GraphDataexport interface GraphConfigData { nodes?: NodeConfig[] edges?: EdgeConfig[] } export interface GraphData { nodes: NodeData[] edges: EdgeData[] }两者的区别GraphConfigData是输入配置nodes/edges均可省略节点id可缺省由框架自动生成GraphData是输出快照nodes/edges必填所有id已解析。getGraphRawData返回GraphDatarenderRawData接受GraphConfigData。NodeConfig / NodeData 关键字段字段类型说明idstring可选节点标识省略时自动生成。typestring必填已注册的节点类型名。x/ynumber画布坐标中心点基准。textTextConfig \| string可选节点文本。zIndexnumber可选层级。propertiesPropertiesType可选业务自定义属性容器。virtualboolean可选标记为虚拟节点不进入导出数据。rotatenumber可选旋转角度。rotatable/resizableboolean可选交互控制开关。EdgeConfig / EdgeData 关键字段字段类型说明typestring可选边类型内部默认为polyline。sourceNodeId/targetNodeIdstring必填起止节点 id。sourceAnchorId/targetAnchorIdstring可选起止锚点 id。startPoint/endPointPoint可选手动指定的起止坐标。pointsListPoint[]可选折线拐点。textstring \| TextConfig可选边标签。七、实战组合模式将以上 API 组合起来可以形成一套标准的数据加载—编辑—导出闭环// 1. 加载业务数据业务结构如后端 DSL lf.adapterIn (biz) ({ nodes: biz.processNodes.map((n) ({ id: n.id, type: n.type, x: n.cx, y: n.cy, properties: n.props, })), edges: biz.processEdges, }); lf.render(bizData); // 2. 编辑过程中需要内部结构做校验/布局时走原生通道 const raw lf.getGraphRawData(); // GraphData永远稳定 // 3. 保存时输出业务结构支持调用期传入额外选项 lf.adapterOut (data, { keepLayout }) ({ processNodes: data.nodes.map((n) (keepLayout ? n : { ...n, x: 0, y: 0 })), processEdges: data.edges, }); const saved lf.getGraphData({ keepLayout: false }); // 4. 重新编辑或重置 lf.clearData();八、最佳实践小结插件开发者走原生通道内部依赖结构的通用插件一律使用renderRawData/getGraphRawData避免被业务适配器干扰。业务接入走适配通道renderadapterIn、getGraphDataadapterOut的组合将数据结构差异隔离在薄薄一层映射函数中。adapterOut善用...params把导出选项设计为getGraphData的调用期参数而不是全局状态保证适配器可复用、可测试。注意render的整图替换语义需要增量增删节点时应使用addNode/addEdge等模型 API而不是反复调用render。渲染后如需立即操作模型监听GRAPH_RENDERED事件回调中即可拿到graphModel与数据快照。以上所有实现细节均可直接在仓库源码中验证实例方法实现见 packages/core/src/LogicFlow.tsx模型层数据转换见 packages/core/src/model/GraphModel.ts类型定义见 sites/docs/docs/api/type/MainTypes.en.md。【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考