LogicFlow：滴滴开源流程图编辑引擎安装与使用指南

一、项目官方信息

项目	信息
GitHub 仓库	didi/LogicFlow
官方文档	site.logic-flow.cn
开源协议	Apache-2.0 License
核心包	@logicflow/core、@logicflow/extension、@logicflow/layout
Star 数	约 11.7k（截至本文发布时实时数据）

二、项目背景

按照官方 README 的定义，LogicFlow 是一款流程图编辑框架，由滴滴团队开源。它要解决的问题非常具体：在企业内部业务系统里，"类流程图"的需求无处不在——审批流设计器、工单流转图、请假流程配置、业务编排画布、BPMN 流程图、ER 图、知识图谱可视化等等，几乎每个中后台产品都绕不开。但直接使用成品流程图库会遇到两个麻烦：一是样式和交互写死，跟自家业务长得不一样；二是图数据只能看不能用，后端执行引擎没法消费。

LogicFlow 的思路是把自己做成"框架"而不是"成品组件"：它提供画布运行时（canvas、节点、边、模型、事件、渲染、主题、基础交互），再提供简单灵活的节点自定义机制和插件扩展体系，让开发者在框架之上快速搭建符合自己业务的流程图应用。README 的原话是"提供了一系列流程图交互、编辑所必需的功能和简单灵活的节点自定义、插件等拓展机制，方便我们快速在业务系统内满足类流程图的需求"。

也正是因为这种"框架而非组件"的定位，LogicFlow 的适用面很广：业务开发者既可以用它搭一个纯展示的流程图只读页面，也可以搭一个可拖拽编辑、可导出 JSON、可对接后端执行引擎的完整流程设计器。README 强调"简单灵活"——节点自定义与插件机制都不复杂，但组合起来能覆盖相当多的业务场景。

从仓库结构上看，项目采用 pnpm 管理的 monorepo：packages/core 是核心画布运行时，packages/extension 是官方插件包（内部又包含 bpmn-elements、bpmn-elements-adapter、tools/snapshot 等子模块），packages/layout 提供自动布局插件，packages/react-node-registry 与 packages/vue-node-registry 分别提供 React 与 Vue 生态下的自定义节点注册能力；examples 目录下则放了 vue3-app、next-app、material-ui-demo、engine-browser-examples、dynamic-group-regression 等多个可运行的示例工程。README 顶部同时展示了 npm 版本徽章、月下载量徽章与开源协议徽章，说明它是一个以 npm 包形式持续发布的成熟项目。

三、官方图片

LogicFlow 仓库封面

上图为 LogicFlow 仓库在 GitHub 上的官方封面图。项目官网地址为 site.logic-flow.cn，官网头部有官方 Logo，npm 包版本徽章也同步展示在 README 顶部，分别对应 npm 版本、月下载量与开源协议三项指标。如果想直观感受它的能力边界，最直接的方式是打开官网文档里的图表示例页面，逐个查看可交互的 demo。

四、核心能力（README 原文逐条展开）

官方 README 在"核心能力"一节列出五条，这里逐条说明其含义：

可视化模型：通过 LogicFlow 提供的直观可视化界面，用户可以轻松创建、编辑和管理复杂的逻辑流程图。也就是说，画布上的一切——节点、连线、文本、拖拽选区——都是可交互的可视化对象；而画布背后维护着一份结构化的图数据模型，用户在界面上画的每一笔都会同步反映到这份数据上，最终可以导出为 JSON 供后端或执行引擎使用。
高可定制性：用户可以根据自己的需要定制节点、连接器和样式，创建符合特定用例的定制逻辑流程图。不同业务的流程图差异很大：有的要泳道分区，有的要抽屉式属性面板，有的要自定义锚点和连线规则，LogicFlow 的节点自定义机制就是为这类差异化设计的。
灵活易拓展：内置提供丰富的插件，用户也可根据自身需求定制复杂插件实现业务需求。README 明确了三个 npm 包的分工：@logicflow/core 是核心图编辑器运行时，包含画布、节点、边、模型、事件、渲染、主题和基础交互；@logicflow/extension 是面向常见产品功能的官方插件包；@logicflow/layout 是面向自动图布局的官方布局插件。项目本身采用 monorepo 结构，仓库下 packages/core、packages/extension、packages/layout、packages/react-node-registry、packages/vue-node-registry 等目录分别对应这些包，examples 目录下则提供了 vue3-app、next-app、material-ui-demo、engine-browser-examples 等多个示例工程。
自执行引擎：执行引擎支持浏览器端执行流程图逻辑，为无代码执行提供新思路。画出来的流程图不只是"静态图"，还可以在浏览器里顺着节点定义的逻辑直接跑起来，这是它区别于普通流程图插件的重要特性。
数据可转换：支持 LogicFlow 数据与 BPMN、Turbo 等各种后端执行引擎数据结构转换能力。这意味着前端设计态画的流程图可以无损转换成后端能识别的标准格式，打通"设计态"与"运行态"，这是企业级流程平台最关键的一环。

五、环境要求

现代浏览器：LogicFlow 是纯前端框架，不依赖任何后端服务即可渲染与交互画布，在桌面端主流浏览器中都能正常工作；
Node.js 环境：用于通过 npm、yarn 或 pnpm 安装依赖包，建议使用较新版本的 Node 以保证 pnpm monorepo 工具链可用；
随包文档：@logicflow/core@2.2.2 及以上版本会在包内附带官方本地文档（位于 node_modules/@logicflow/core/dist/docs/），这是官方专门为 AI 编程工具提供的离线文档能力，联网不可用时也能查阅；
框架兼容性：LogicFlow 与框架无关，原生 JS/TS 项目可直接使用，仓库同时提供 React 节点注册包与 Vue 节点注册包，在 React、Vue 技术栈中均可接入。

六、安装步骤

官方 README 给出了三种主流包管理器的安装命令，核心包与扩展包需同时安装：

# npm
$ npm install @logicflow/core @logicflow/extension --save

# yarn
$ yarn add @logicflow/core @logicflow/extension

# pnpm
$ pnpm add @logicflow/core @logicflow/extension

三个命令效果等价，按团队包管理习惯选择其一即可：npm install ... --save 是最通用的写法；yarn add 与 pnpm add 分别对应 yarn 与 pnpm 用户。安装完成后两个包会进入项目依赖树，业务代码里通过 import LogicFlow from '@logicflow/core' 引入画布运行时，需要的插件再从 @logicflow/extension 中按需引入。其中 @logicflow/core 提供画布运行时，@logicflow/extension 提供常用产品功能插件；如果项目还需要自动布局能力，再额外安装 @logicflow/layout 即可，无需改动核心包。

七、使用方法

7.1 准备容器

在页面中放置一个用来承载画布的 DOM 容器：

<!-- LogicFlow 容器 DOM-->
<div id="container"></div>;

容器可以是任意块级元素，后续实例化时通过 container 配置项把它交给 LogicFlow。

7.2 准备数据并渲染画布

README 的快速上手示例展示了最基本的用法：先声明节点数组与边数组，再实例化 LogicFlow 并调用 render：

// 准备数据
const data = {
  // 节点
  nodes: [
    {
      id: '21',
      type: 'rect',
      x: 100,
      y: 200,
      text: '矩形节点',
    },
    {
      id: '50',
      type: 'circle',
      x: 300,
      y: 400,
      text: '圆形节点',
    },
  ],
  // 边
  edges: [
    {
      type: 'polyline',
      sourceNodeId: '50',
      targetNodeId: '21',
    },
  ],
};
// 渲染画布
const lf = new LogicFlow({
  container: document.querySelector('#container'),
  width: 700,
  height: 600,
});

lf.render(data);

逐段说明：节点数组 nodes 里有两个节点。第一个节点 id 为 21，type 为 rect（矩形），坐标 x:100、y:200，显示文本为"矩形节点"；第二个节点 id 为 50，type 为 circle（圆形），坐标 x:300、y:400，显示文本为"圆形节点"。边数组 edges 里有一条折线，type 为 polyline，起点 sourceNodeId 是 50，终点 targetNodeId 是 21。实例化时，container 指向刚才准备的 DOM，width 与 height 分别为 700 与 600。最后调用 lf.render(data) 把数据渲染到画布上。

可以看到，这份数据就是以节点数组、边数组为核心的结构化 JSON：每个节点用 id 唯一标识，用 type 指定形状（矩形、圆形等内置或自定义形状），用 x、y 指定画布坐标，用 text 指定节点上显示的文字；每条边用 sourceNodeId 与 targetNodeId 指定两端节点，用 type 指定连线形式（这里是 polyline 折线）。业务方完全可以把这份 JSON 直接存库、下发、二次编辑，或者转换成 BPMN、Turbo 等后端执行引擎需要的格式——这正是 README 所说"数据可转换"能力的落地方式。实例返回的 lf 实例上还会挂载后续操作画布、监听事件、导出数据的各种方法，后续业务开发都围绕这个实例展开。

7.3 AI 编程支持（README 专属章节）

LogicFlow 为 AI 编程工具提供了随 npm 包发布的本地文档。README 建议：安装或升级后，把下面这段提示词复制给你的 AI Agent，让它在实现 LogicFlow 功能之前先查官方文档。更多说明请查看 AI 编程支持。

<!-- BEGIN:logicflow-agent-rules -->
# LogicFlow Agent Rules

LogicFlow documentation is available at:

- `node_modules/@logicflow/core/dist/docs/`

Package roles:

- `@logicflow/core`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions.
- `@logicflow/extension`: official plugins for common product features.
- `@logicflow/layout`: official layout plugins for automatic graph layout.

The docs for `@logicflow/extension` and `@logicflow/layout` are included under:

- `node_modules/@logicflow/core/dist/docs/tutorial/extension/`

Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch.

If an official package is needed but not installed, ask the user before installing it.
<!-- END:logicflow-agent-rules -->

这段规则翻译成中文意思是：LogicFlow 文档位于 node_modules/@logicflow/core/dist/docs/；三个包的角色分别为核心运行时、官方插件、布局插件，扩展包与布局包的文档放在 docs/tutorial/extension/ 子目录下。AI 在动手实现任何 LogicFlow 功能之前，应先查本地文档，确认框架是否已经提供了内置能力、扩展或布局插件——如果有，优先使用官方已文档化的能力，而不是从零重写；如果需要某个官方包但尚未安装，应先询问用户再安装。这套规则的价值在于避免 AI 重复造轮子：很多常见需求（如快照、菜单、工具栏、BPMN 元素）官方插件早已实现，直接引用比手写代码更稳定。

7.4 本地开发（参与源码贡献）

如果需要从源码本地开发 LogicFlow，README 给出的流程是：

# 安装项目依赖（prepare 会自动跑 build:all）
$ pnpm install

# 终端 1：监听 packages，热更新 es/lib
$ pnpm run dev

# 终端 2：启动 demo
$ cd examples/feature-examples && pnpm dev

即先用 pnpm install 安装项目依赖（prepare 钩子会自动执行全量构建），然后在第一个终端监听 packages 目录实现 es/lib 产物热更新，在第二个终端进入 examples/feature-examples 启动示例工程，做到边改源码边看效果。README 同时提示：依赖安装完成后，prepare 阶段会自动执行 build:all，所以首次 install 完成即得到可调试的构建产物。

八、相关文档与社区资源

README 在"相关文档"一节给出了官方文档入口及几个关键子站，这里逐一说明：

官方文档首页：完整教程、API 与示例的总入口；
快速上手：面向第一次接触 LogicFlow 的开发者的入门教程；
图表示例：大量可直接运行的流程图示例集合；
相关文章：LogicFlow 架构：解释框架整体架构设计的文章；
更新日志：每个版本的变更记录；
Issue 模板：按官方模板提 issue，便于维护者快速定位问题。

README 还提供了 Star History 趋势图，可以直观看到项目获星数随时间的增长曲线；贡献者名单则以 CONTRIBUTORS 图表的形式展示在 GitHub 仓库主页。

九、常见问题（FAQ）

问：只安装 @logicflow/core 够不够？ 答：官方安装命令是 @logicflow/core 与 @logicflow/extension 一起安装。核心包负责画布与基础交互，扩展包提供常用产品功能插件，实际业务几乎都会用到，建议一并安装。
问：AI 辅助开发需要额外配文档吗？ 答：不需要。随包本地文档从 @logicflow/core@2.2.2 版本开始附带，升级到该版本以上后直接把官方提示词交给 AI Agent 即可。
问：画出来的图能给后端执行引擎用吗？ 答：可以。README 明确支持 LogicFlow 数据与 BPMN、Turbo 等后端执行引擎数据结构互转，画布数据本身就是结构化 JSON，可直接持久化。
问：想参与共建怎么办？ 答：遵从官方贡献指南提交 PR；贡献度足够活跃时，可以申请成为社区协作者。
问：开源协议是什么？ 答：项目代码和文档基于 Apache-2.0 License 开源，商业项目也可放心集成。
问：官方文档里有哪些可直接学习的资源？ 答：除了官方文档首页，还推荐按顺序看快速上手、图表示例集合与架构解读文章，前者动手，中者看效果，后者懂原理。
问：本地开发需要几个终端？ 答：README 演示的是两个终端：一个跑 pnpm run dev 监听 packages，另一个进入 examples/feature-examples 跑 pnpm dev 启动 demo，两者配合实现热更新调试。

LogicFlow：滴滴开源流程图编辑引擎安装与使用指南

LogicFlow：滴滴开源流程图编辑引擎安装与使用指南

一、项目官方信息

二、项目背景

三、官方图片

四、核心能力（README 原文逐条展开）

五、环境要求

六、安装步骤

七、使用方法

7.1 准备容器

7.2 准备数据并渲染画布

7.3 AI 编程支持（README 专属章节）

7.4 本地开发（参与源码贡献）

八、相关文档与社区资源

九、常见问题（FAQ）

十、跳转链接

周若琳

文章目录