React Flow 架构

何时使用 React Flow

适用场景

• - 可视化编程界面
• 工作流构建器和自动化工具
• 图表编辑器（流程图、组织结构图）
• 数据管道可视化
• 思维导图工具
• 基于节点的音视频编辑器
• 决策树构建器
• 状态机设计器

考虑替代方案

• - 简单静态图表（直接使用 SVG 或 Canvas）
• 高实时性协作（可能需要自定义同步层）
• 3D 可视化（使用 Three.js、react-three-fiber）
• 超过 1 万个节点的图分析（使用基于 WebGL 的解决方案，如 Sigma.js）

架构模式

包结构（xyflow）

@xyflow/system（原生 TypeScript）
├── 核心算法（边路径、边界、视口）
├── xypanzoom（基于 d3 的平移/缩放）
├── xydrag、xyhandle、xyminimap、xyresizer
└── 共享类型

@xyflow/react（依赖 @xyflow/system）
├── React 组件和钩子
├── 用于状态管理的 Zustand 存储
└── 框架特定集成

@xyflow/svelte（依赖 @xyflow/system）
└── Svelte 组件和存储

含义：核心逻辑与框架无关。在贡献或调试时，检查问题是在 @xyflow/system 还是框架特定包中。

状态管理方法

1. 本地状态（简单应用）

tsx
// 使用 useNodesState/useEdgesState 进行原型开发
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

优点：简单，样板代码少
缺点：状态局限于组件树

2. 外部存储（生产环境）

tsx
// Zustand 存储示例
import { create } from zustand;

interface FlowStore {
nodes: Node[];
edges: Edge[];
setNodes: (nodes: Node[]) => void;
onNodesChange: OnNodesChange;
}

const useFlowStore = create((set, get) => ({
nodes: initialNodes,
edges: initialEdges,
setNodes: (nodes) => set({ nodes }),
onNodesChange: (changes) => {
set({ nodes: applyNodeChanges(changes, get().nodes) });
},
}));

// 在组件中
function Flow() {
const { nodes, edges, onNodesChange } = useFlowStore();
return ;
}

优点：状态随处可访问，更易持久化/同步
缺点：需要更多设置，需谨慎优化选择器

3. Redux/其他状态库

tsx
// 通过选择器连接
const nodes = useSelector(selectNodes);
const dispatch = useDispatch();

const onNodesChange = useCallback((changes: NodeChange[]) => {
dispatch(nodesChanged(changes));
}, [dispatch]);

数据流架构

用户输入 → 变更事件 → 归约器/处理器 → 状态更新 → 重新渲染
↓
[拖拽节点] → onNodesChange → applyNodeChanges → setNodes → ReactFlow
↓
[连接] → onConnect → addEdge → setEdges → ReactFlow
↓
[删除] → onNodesDelete → deleteElements → setNodes/setEdges → ReactFlow

子流程模式（嵌套节点）

tsx
// 包含子节点的父节点
const nodes = [
{
id: group-1,
type: group,
position: { x: 0, y: 0 },
style: { width: 300, height: 200 },
},
{
id: child-1,
parentId: group-1, // 关键：父节点引用
extent: parent, // 关键：限制在父节点内
position: { x: 10, y: 30 }, // 相对于父节点
data: { label: 子节点 },
},
];

注意事项：

• - 使用 extent: parent 限制拖拽范围
• 使用 expandParent: true 自动扩展父节点
• 父节点的 z-index 影响子节点渲染顺序

视口持久化

tsx
// 保存视口状态
const { toObject, setViewport } = useReactFlow();

const handleSave = () => {
const flow = toObject();
// flow.nodes, flow.edges, flow.viewport
localStorage.setItem(flow, JSON.stringify(flow));
};

const handleRestore = () => {
const flow = JSON.parse(localStorage.getItem(flow));
setNodes(flow.nodes);
setEdges(flow.edges);
setViewport(flow.viewport);
};

集成模式

与后端/API 集成

tsx
// 从 API 加载
useEffect(() => {
fetch(/api/flow)
.then(r => r.json())
.then(({ nodes, edges }) => {
setNodes(nodes);
setEdges(edges);
});
}, []);

// 防抖自动保存
const debouncedSave = useMemo(
() => debounce((nodes, edges) => {
fetch(/api/flow, {
method: POST,
body: JSON.stringify({ nodes, edges }),
});
}, 1000),
[]
);

useEffect(() => {
debouncedSave(nodes, edges);
}, [nodes, edges]);

与布局算法集成

tsx
import dagre from dagre;

function getLayoutedElements(nodes: Node[], edges: Edge[]) {
const g = new dagre.graphlib.Graph();
g.setGraph({ rankdir: TB });
g.setDefaultEdgeLabel(() => ({}));

nodes.forEach((node) => {
g.setNode(node.id, { width: 150, height: 50 });
});

edges.forEach((edge) => {
g.setEdge(edge.source, edge.target);
});

dagre.layout(g);

return {
nodes: nodes.map((node) => {
const pos = g.node(node.id);
return { ...node, position: { x: pos.x, y: pos.y } };
}),
edges,
};
}

性能扩展

节点数量指南

优化技术

tsx
// 仅渲染视口内的节点/边
onlyRenderVisibleElements={true}

// 减少节点边框半径（改善相交计算）
nodeExtent={[[-1000, -1000], [1000, 1000]]}

// 禁用不需要的功能
elementsSelectable={false}
panOnDrag={false}
zoomOnScroll={false}
/>

权衡

受控 vs 非受控

连接模式

tsx

边渲染