【前端知识】React Flow : 一个基于 React 的可视化节点编辑器框架

React Flow : 一个基于 React 的可视化节点编辑器框架

[一、React Flow 是什么？（核心概念）](#一、React Flow 是什么？（核心概念）)
- [1️⃣ 核心概念速览](#1️⃣ 核心概念速览)
- [2️⃣ React Flow 不是什么](#2️⃣ React Flow 不是什么)
[二、React Flow 能实现哪些功能？](#二、React Flow 能实现哪些功能？)
- [✅ 1. 基础可视化能力（开箱即用）](#✅ 1. 基础可视化能力（开箱即用）)
- [✅ 2. 高度可定制节点（非常关键）](#✅ 2. 高度可定制节点（非常关键）)
- [✅ 3. 状态驱动（工程化核心）](#✅ 3. 状态驱动（工程化核心）)
- [✅ 4. 事件系统（构建"真正可用的工具"）](#✅ 4. 事件系统（构建“真正可用的工具”）)
- [✅ 5. 高级能力（企业级）](#✅ 5. 高级能力（企业级）)
[三、React Flow 完整使用教程（工程级）](#三、React Flow 完整使用教程（工程级）)
- [Step 1：环境准备](#Step 1：环境准备)
- [Step 2：安装依赖](#Step 2：安装依赖)
- [Step 3：Tailwind 基础配置](#Step 3：Tailwind 基础配置)
- [Step 4：全局样式](#Step 4：全局样式)
- [Step 5：流程状态管理（Zustand）](#Step 5：流程状态管理（Zustand）)
- [Step 6：自定义节点](#Step 6：自定义节点)
- [Step 7：注册节点类型](#Step 7：注册节点类型)
- [Step 8：主画布](#Step 8：主画布)
- [Step 9：初始化流程数据](#Step 9：初始化流程数据)
- [Step 10：构建 & 部署](#Step 10：构建 & 部署)
[四、使用 React Flow 构建 AI 工作流工具（实战）](#四、使用 React Flow 构建 AI 工作流工具（实战）)
- [✅ 一个典型的 AI 工作流结构](#✅ 一个典型的 AI 工作流结构)
- [✅ 节点设计（推荐）](#✅ 节点设计（推荐）)
- [✅ 与 LangGraph / MCP 的关系](#✅ 与 LangGraph / MCP 的关系)
- [✅ 执行联动示意](#✅ 执行联动示意)
五、总结（重点）

一、React Flow 是什么？（核心概念）

React Flow 是一个基于 React 的可视化节点编辑器框架，用于构建流程图、DAG、工作流、规则引擎 UI。

它不是"画图库"，而是：

✅ 可交互、可编排、可工程化嵌入的节点系统

1️⃣ 核心概念速览

概念	说明
Node	流程中的节点（一个步骤 / 一个 Agent / 一个算子）
Edge	节点之间的连线（数据流向 / 控制流向）
Handle	节点上的"连接点"（输入 / 输出）
Port	Handle 的高级称呼
Flow Instance	ReactFlow 组件实例
Node Types	可注册的自定义节点类型
Edge Types	可自定义的连线类型

2️⃣ React Flow 不是什么

❌ 不是 Figma / X6 / SVG 画图工具

❌ 不自带"执行引擎"

✅ 只负责"可视化 + 交互"

真正的"工作流执行"需要你自己实现（或对接 LangGraph / 后端 DAG）

二、React Flow 能实现哪些功能？

✅ 1. 基础可视化能力（开箱即用）

节点拖拽
画布缩放 / 平移
节点多选 / 框选
连线吸附
对齐辅助线
键盘快捷键（删除 / 复制 / 粘贴）

👉 这是构建"工作流工具"的基础设施

✅ 2. 高度可定制节点（非常关键）

你可以把任何 React 组件作为节点：

tsx 复制代码

const CustomNode = ({ data }) => (
  <div className="agent-node">
    <h4>{data.label}</h4>
    <button onClick={data.onRun}>执行</button>
  </div>
);

✅ 意味着你可以放：

表单
状态灯
下拉框
日志面板
AI Agent 状态

✅ 3. 状态驱动（工程化核心）

React Flow 的状态是纯 JSON：

ts 复制代码

{
  nodes: [{ id, type, position, data }],
  edges: [{ id, source, target }]
}

✅ 可以被：

保存到数据库
从后端加载
与 Zustand / Redux 联动
与 LangGraph 状态对齐

✅ 4. 事件系统（构建"真正可用的工具"）

事件	用途
onNodesChange	节点移动 / 删除
onEdgesChange	连线变化
onConnect	新建连线
onNodeClick	打开配置面板
onPaneClick	空白处点击

✅ 5. 高级能力（企业级）

✅ 子流程（Node 内嵌 Flow）
✅ 自动布局（dagre / elk）
✅ 撤销 / 重做
✅ 自定义 Edge（带箭头、动画）
✅ 大数据量（虚拟化）

三、React Flow 完整使用教程（工程级）

下面给你一个可直接上线使用的完整流程。

Step 1：环境准备

bash 复制代码

node -v   # >= 18
npm create vite@latest my-flow-app -- --template react-ts
cd my-flow-app

Step 2：安装依赖

bash 复制代码

npm install reactflow zustand
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Step 3：Tailwind 基础配置

tailwind.config.js

js 复制代码

export default {
  content: ['./index.html', './src/**/*.{ts,tsx}'],
};

Step 4：全局样式

src/index.css

css 复制代码

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 5：流程状态管理（Zustand）

src/store/flowStore.ts

ts 复制代码

import { create } from 'zustand';
import { Node, Edge } from 'reactflow';

type FlowState = {
  nodes: Node[];
  edges: Edge[];
  setNodes: (nodes: Node[]) => void;
  setEdges: (edges: Edge[]) => void;
};

export const useFlowStore = create<FlowState>((set) => ({
  nodes: [],
  edges: [],
  setNodes: (nodes) => set({ nodes }),
  setEdges: (edges) => set({ edges }),
}));

Step 6：自定义节点

src/nodes/AgentNode.tsx

tsx 复制代码

import { Handle, Position } from 'reactflow';

export function AgentNode({ data }: any) {
  return (
    <div className="bg-white border p-3 rounded shadow min-w-[180px]">
      <Handle type="target" position={Position.Top} />
      <h4 className="font-bold">{data.label}</h4>
      <div className="text-xs text-gray-500 mb-2">{data.model}</div>
      <button
        className="bg-blue-500 text-white px-2 py-1 rounded"
        onClick={data.onRun}
      >
        执行
      </button>
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

Step 7：注册节点类型

ts 复制代码

const nodeTypes = {
  agent: AgentNode,
};

Step 8：主画布

src/pages/FlowEditor.tsx

tsx 复制代码

import ReactFlow, { Controls, Background } from 'reactflow';
import 'reactflow/dist/style.css';
import { useFlowStore } from '../store/flowStore';
import { nodeTypes } from '../nodes';

export default function FlowEditor() {
  const { nodes, edges, setNodes, setEdges } = useFlowStore();

  return (
    <div className="h-screen w-full">
      <ReactFlow
        nodes={nodes}
        edges={edges}
        nodeTypes={nodeTypes}
        onNodesChange={(changes) =>
          setNodes(
            changes.reduce((acc, c) => {
              if (c.type === 'position') {
                return acc.map((n) =>
                  n.id === c.id ? { ...n, position: c.position! } : n
                );
              }
              return acc;
            }, nodes)
          )
        }
        onEdgesChange={(changes) =>
          setEdges(
            changes.reduce((acc, c) => {
              if (c.type === 'remove') {
                return acc.filter((e) => e.id !== c.id);
              }
              return acc;
            }, edges)
          )
        }
        fitView
      >
        <Controls />
        <Background />
      </ReactFlow>
    </div>
  );
}

Step 9：初始化流程数据

ts 复制代码

useFlowStore.setState({
  nodes: [
    {
      id: '1',
      type: 'agent',
      position: { x: 100, y: 100 },
      data: { label: 'LLM Agent', model: 'GPT-4o', onRun: () => {} },
    },
  ],
  edges: [],
});

Step 10：构建 & 部署

bash 复制代码

npm run build

✅ 可部署到：

Vercel
Netlify
Docker + Nginx

四、使用 React Flow 构建 AI 工作流工具（实战）

✅ 一个典型的 AI 工作流结构

text 复制代码

用户输入
   ↓
意图识别 Agent
   ↓
工具选择
   ↓
工具执行
   ↓
结果聚合

✅ 节点设计（推荐）

节点类型	含义
InputNode	用户输入
AgentNode	LLM / Agent
ToolNode	工具调用
ConditionNode	条件分支
OutputNode	输出

✅ 与 LangGraph / MCP 的关系

层	技术
执行引擎	LangGraph
可视化	React Flow
协议	MCP
状态同步	JSON + WebSocket

✅ React Flow 负责：

节点编排 UI
状态展示
用户交互

✅ LangGraph 负责：

真正执行流程
状态推进

✅ 执行联动示意

ts 复制代码

onClickRunAgent(nodeId) {
  const flow = useFlowStore.getState();
  fetch('/api/langgraph/run', {
    method: 'POST',
    body: JSON.stringify(flow),
  });
}

五、总结（重点）

✅ React Flow 的核心价值

把"流程编排"变成可交互、可维护、可工程化的前端系统

✅ 什么时候该用 React Flow？

AI 工作流编辑器
Agent 编排 UI
规则引擎
低代码平台

✅ 什么时候不该用？

纯展示流程图
非交互型图表