深入浅出 React Flow：交互式节点图构建利器 소개 및 핵심 개념 상세 설명

在现代 Web 应用开发中，构建复杂、交互式的可视化界面是常有的需求，尤其是在涉及流程图、数据关系图、编辑器、数据分析等领域。传统的做法可能需要开发者从零开始处理 SVG、Canvas 甚至 DOM 操作，来绘制节点和连线，并处理复杂的交互逻辑（如拖拽、缩放、连接、编辑）。这无疑是耗时且容易出错的。

正是在这样的背景下，像 React Flow 这样的库应运而生。React Flow 是一个为 React 应用量身打造的、用于构建节点图和交互式图表的库。它提供了一系列强大的组件和钩子（Hooks），极大地简化了节点图的开发过程，让开发者能够专注于业务逻辑而非底层的图形绘制和交互细节。

本文将带您深入了解 React Flow，从它的基本介绍出发，详细剖析其核心概念，帮助您掌握使用 React Flow 构建复杂交互式节点图的能力。

1. React Flow 简介

什么是 React Flow？

React Flow 是一个开源的 React 库，专门用于在 Web 浏览器中创建可定制的、交互式的节点图。它基于 SVG 渲染，提供了高性能的平移（Pan）、缩放（Zoom）功能，支持多种节点类型和边类型，并且提供了灵活的 API 来管理图的状态和处理用户交互。

为什么选择 React Flow？

基于 React： 作为 React 生态的一部分，React Flow 天然地与 React 的组件化、声明式编程范式结合。您可以轻松地将 React 组件作为节点或边的内容，利用 React 的状态管理和生命周期。
高性能： 借助 SVG 渲染和内部优化，React Flow 能够流畅地处理包含成百上千个节点和边的复杂图表。
高度可定制： 几乎所有的元素——节点、边、句柄（Handles）、背景、控件等都可以进行自定义。您可以创建完全符合您应用风格和需求的图表。
强大的交互性： 内建了平移、缩放、节点拖拽、边连接等基础交互。通过丰富的事件回调，您可以轻松地添加自定义的交互行为。
灵活的状态管理： React Flow 提供了方便的 Hook 来管理图的状态（节点和边的数据），并与外部状态管理库（如 Redux, Zustand, Context API）兼容。
易于上手： 提供了清晰的文档和示例，对于熟悉 React 的开发者来说，入门曲线相对平缓。

典型应用场景：

工作流/流程编辑器： 构建自动化流程、审批流程等的可视化编辑界面。
数据管道/ETL 工具： 展示数据处理流程中的各个步骤和数据流向。
机器学习/AI 模型构建器： 可视化神经网络结构或模型训练流程。
组织结构图： 展示公司或团队的层级关系。
思维导图/概念图： 创建节点连接的非线性结构图。
网络拓扑图： 展示网络设备及其连接关系。
状态机编辑器： 可视化和编辑状态机的状态和转换。

2. 核心概念详解

理解 React Flow 的核心概念是使用它的关键。以下是构成 React Flow 图表的基本要素：

2.1 ReactFlowProvider

ReactFlowProvider 是 React Flow 的上下文提供者。它是使用 ReactFlow 组件或任何 React Flow 钩子（如 useReactFlow, useNodesState, useEdgesState 等）的必要外部包裹层。

作用：

它在 React 上下文中存储和管理 React Flow 实例的内部状态、配置和方法。
使得在其内部的任何子组件都可以通过钩子访问 React Flow 实例，进行状态管理或调用方法。

用法：

“`jsx
import { ReactFlowProvider } from ‘reactflow’;

function App() {
return (

{/ 您的 React Flow 图表组件 /}

);
}
“`

通常，您只需要在应用程序的根部或包含所有图表组件的父组件中放置一个 ReactFlowProvider。

2.2 Nodes (节点)

节点是图表中最基本的元素，代表了图中的实体。每个节点都需要一个唯一的 ID 和一个位置。

核心属性：

id: (string) 节点的唯一标识符。必须提供。
position: ({ x: number, y: number }) 节点在图表空间中的位置。通常表示节点的左上角坐标。必须提供。
data: (object) 与节点关联的任意数据。您可以在自定义节点组件中通过 props 访问这些数据，用于渲染节点的内容。
type: (string) 节点的类型。默认为 'default'。通过定义不同的节点类型，您可以渲染不同样式的节点。
style: (object) 应用于节点外层 DOM 元素的行内样式。
className: (string) 应用于节点外层 DOM 元素的 CSS 类名。
selected: (boolean) 节点当前是否被选中。通常由 React Flow 自动管理，但您也可以通过状态控制。
draggable: (boolean) 节点是否可拖拽。默认为 true。
selectable: (boolean) 节点是否可选中。默认为 true。
connectable: (boolean) 节点是否可以连接（即其句柄是否可以被用来创建新边）。默认为 true。
deletable: (boolean) 节点是否可以通过 Delete/Backspace 键删除。默认为 false。
targetPosition: (‘top’ | ‘right’ | ‘bottom’ | ‘left’) 该节点接收边的默认位置（如果没有使用句柄）。
sourcePosition: (‘top’ | ‘right’ | ‘bottom’ | ‘left’) 该节点发出边的默认位置（如果没有使用句柄）。

示例节点数据结构：

javascript const initialNodes = [ { id: '1', position: { x: 100, y: 100 }, data: { label: '节点 1' }, type: 'default', // 使用默认节点类型 }, { id: '2', position: { x: 300, y: 200 }, data: { label: '节点 2' }, type: 'customNode', // 使用自定义节点类型 (稍后介绍) draggable: false, // 这个节点不可拖拽 }, ];

2.3 Edges (边/连线)

边代表了节点之间的连接关系。一条边连接了两个节点（源节点和目标节点）。边可以连接整个节点，也可以连接到节点上特定的句柄（Handle）。

核心属性：

id: (string) 边的唯一标识符。必须提供。通常使用源节点ID、目标节点ID和句柄ID组合生成，例如 'edge-1-2' 或 'edge-node1-handleA-node2-handleB'。
source: (string) 源节点的 ID。必须提供。
target: (string) 目标节点的 ID。必须提供。
sourceHandle: (string) 源节点上用于连接的句柄 ID (如果使用了句柄)。可选。
targetHandle: (string) 目标节点上用于连接的句柄 ID (如果使用了句柄)。可选。
type: (string) 边的类型。默认为 'default' (贝塞尔曲线)。其他内置类型包括 'step', 'straight', 'simplebezier'。您也可以定义自定义边类型。
label: (ReactNode) 显示在边上的标签。可以是字符串或任何 React 元素。
labelStyle: (object) 应用于标签的样式。
labelShowBg: (boolean) 是否给标签显示背景框。
animated: (boolean) 边是否带有动画效果（例如，流动的点）。
style: (object) 应用于边路径的行内样式。
className: (string) 应用于边外层 DOM 元素的 CSS 类名。
selected: (boolean) 边当前是否被选中。
data: (object) 与边关联的任意数据。
markerStart: (string | object) 添加到边起点的箭头或其他标记。可以是一个 SVG 标记 ID 或一个标记配置对象。
markerEnd: (string | object) 添加到边终点的箭头或其他标记。可以是一个 SVG 标记 ID 或一个标记配置对象。
updatable: (boolean | ‘source’ | ‘target’) 边是否可更新（即拖拽边两端重新连接）。true 表示两端都可更新，'source' 只更新起点，'target' 只更新终点。默认为 true。
deletable: (boolean) 边是否可以通过 Delete/Backspace 键删除。默认为 false。

示例边数据结构：

javascript const initialEdges = [ { id: 'edge-1-2', source: '1', target: '2', type: 'default', // 使用默认边类型 label: '连接', animated: true, // 边带动画 }, { id: 'edge-2-3', source: '2', target: '3', type: 'step', // 使用阶梯线 label: '下一步', markerEnd: { type: 'arrowclosed' }, // 在终点加箭头 }, ];

2.4 Handles (句柄)

句柄是节点上专门用于连接边的小点或区域。通过句柄，您可以精确控制边连接到节点的哪个位置，而不是只能连接到节点的默认位置。

type: (‘source’ | ‘target’) 句柄的类型。'source' 表示这是一个发出边（连接的起点）的句柄；'target' 表示这是一个接收边（连接的终点）的句柄。
position: (‘top’ | ‘right’ | ‘bottom’ | ‘left’) 句柄在节点上的位置。
id: (string) 句柄的唯一标识符。在同一个节点的同类型句柄中必须唯一。用于在边数据中指定连接的是哪个句柄 (sourceHandle, targetHandle)。
isConnectable: (boolean | number) 控制该句柄是否可以建立连接。如果是 boolean，控制是否允许任何连接；如果是 number，控制最多允许多少条连接。
onConnect: (function) 句柄独有的连接事件回调，优先级高于全局的 onConnect。

句柄必须放置在自定义节点组件内部。React Flow 提供了一个 <Handle /> 组件供您使用。

“`jsx
// 在一个自定义节点组件内部
import { Handle, Position } from ‘reactflow’;

function CustomNode({ data }) {
return (

{/ 类型为 source，位置在右边，ID 为 ‘a’ /}

{/ 类型为 target，位置在左边 /}

{data.label}

{/ 类型为 source，位置在下边，ID 为 ‘b’ /}
{/ 这个句柄不能发出连接 /}

);
}
“`

2.5 Viewport (视口)

视口是用户当前在图表区域中看到的部分。React Flow 自动处理图表的平移（Pan）和缩放（Zoom）。

平移： 用户可以拖动图表空白区域来移动视口。
缩放： 用户可以使用鼠标滚轮或触摸板手势来缩放图表。
初始视口： 您可以通过 initialViewport prop 设置图表加载时的初始平移和缩放级别。

jsx <ReactFlow // ... 其他 props initialViewport={{ x: 0, y: 0, zoom: 1 }} // 初始视口在左上角，缩放级别为 1 />

您也可以使用 useReactFlow Hook 提供的 setViewport 或 fitView 方法来程序化地控制视口。

2.6 Controls (控制组件)

React Flow 提供了一些内置的辅助组件，可以放在图表区域内增强用户体验：

<MiniMap />: 一个缩略图，显示整个图表的概览，用户可以在其中导航。
<Controls />: 一组按钮，通常包括缩放（放大/缩小）和适应视图（Fit View）按钮。
<Background />: 在节点图后面绘制网格或点的背景。

这些组件可以直接添加到 <ReactFlow> 组件内部。

“`jsx
import ReactFlow, { MiniMap, Controls, Background } from ‘reactflow’;

function MyFlowChart({ nodes, edges, onNodesChange, onEdgesChange, onConnect }) {
return (

{/ 点状背景 /}

);
}
“`

2.7 State Management (状态管理)

React Flow 的状态主要包括当前显示的所有节点和边的数据。管理这些状态是构建动态图表的关键。React Flow 提供了几种方式来处理状态：

使用 useNodesState 和 useEdgesState Hook (推荐方式):

这是 React Flow 官方推荐的管理节点和边状态的方式。它们返回一个数组，类似于 useState，但还包含一个 onNodesChange 或 onEdgesChange 函数，这个函数已经绑定了 React Flow 内置的事件处理逻辑（如节点拖拽、选中、删除等）。

“`jsx
import React, { useCallback } from ‘react’;
import ReactFlow, {
useNodesState,
useEdgesState,
addEdge,
} from ‘reactflow’;

const initialNodes = [ / … / ];
const initialEdges = [ / … / ];

function MyFlowChart() {
// nodes: 当前节点数组
// setNodes: 更新节点数组的函数
// onNodesChange: 绑定了节点事件处理逻辑的函数
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);

// edges: 当前边数组
// setEdges: 更新边数组的函数
// onEdgesChange: 绑定了边事件处理逻辑的函数
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

// 处理新边连接的逻辑
const onConnect = useCallback(
(params) => setEdges((eds) => addEdge(params, eds)),
[setEdges], // 依赖 setEdges
);

return (

{/ Controls, MiniMap, Background 等 /}

);
}
“`

onNodesChange: 当节点的位置、选中状态、尺寸等发生变化时，React Flow 会触发这个回调。useNodesState 提供的 onNodesChange 函数接收一个变化对象数组作为参数，并能正确地更新 nodes 状态。
onEdgesChange: 当边的选中状态、可更新边的拖拽等发生变化时，React Flow 会触发这个回调。useEdgesState 提供的 onEdgesChange 函数接收一个变化对象数组作为参数，并能正确地更新 edges 状态。
onConnect: 当用户通过拖拽句柄创建一条新边时，React Flow 会触发这个回调，并传入新边的源节点、目标节点及句柄 ID 等信息。您需要在 onConnect 回调中将这条新边添加到 edges 状态中，通常使用 addEdge 辅助函数。

使用 useReactFlow Hook (命令式操作):

useReactFlow Hook 提供了对 React Flow 实例的命令式访问，您可以调用它的方法来执行各种操作，如：

getNodes(): 获取当前所有节点。
getEdges(): 获取当前所有边。
setNodes(nodes): 设置新的节点数组。
setEdges(edges): 设置新的边数组。
addNodes(nodes): 添加一个或多个新节点。
addEdges(edges): 添加一个或多个新边。
deleteElements({ nodes: [...], edges: [...] }): 删除指定的节点和边。
fitView(options): 调整视口以使所有节点可见。
zoomIn(), zoomOut(), zoomTo(zoomLevel): 控制缩放。
setViewport({ x, y, zoom }, options): 设置视口的位置和缩放。
project({ x, y }): 将屏幕坐标转换为图表坐标。
screenToFlow({ x, y }): 将屏幕坐标转换为图表坐标 (与 project 类似，但更直接)。
flowToScreen({ x, y }): 将图表坐标转换为屏幕坐标。

useReactFlow 通常用于在图表外部的组件中触发图表内部的操作，例如点击一个按钮来居中图表，或者在表单提交后添加一个新节点。

“`jsx
import { useReactFlow } from ‘reactflow’;

function ActionBar() {
const reactFlowInstance = useReactFlow();

const fitGraph = () => {
reactFlowInstance.fitView(); // 适应视图
};

return (

);
}
“`

将 ActionBar 放置在 ReactFlowProvider 内部，才能正常使用 useReactFlow Hook。

2.8 Callbacks / Events (回调/事件)

React Flow 提供了丰富的事件回调，让您可以响应用户的各种交互：

onNodesChange(changes): 节点位置、选中状态、尺寸等变化时触发。
onEdgesChange(changes): 边选中状态、可更新边变化时触发。
onConnect(connection): 完成一条新边连接时触发。
onInit(reactFlowInstance): React Flow 初始化完成时触发，会传入 React Flow 实例。常用于在图表加载后立即调用 fitView 等方法。
onNodeClick(event, node): 点击节点时触发。
onEdgeClick(event, edge): 点击边时触发。
onPaneClick(event): 点击图表空白区域时触发。
onNodeDragStart(event, node): 开始拖拽节点时触发。
onNodeDrag(event, node): 拖拽节点过程中触发。
onNodeDragStop(event, node): 停止拖拽节点时触发。
onEdgeUpdateStart(event, edge, handleType): 开始拖拽更新边时触发。
onEdgeUpdate(oldEdge, newConnection): 拖拽更新边完成时触发。
onEdgeUpdateEnd(event, edge, handleType): 停止拖拽更新边时触发。
onMoveStart(event, viewport): 开始平移/缩放时触发。
onMove(event, viewport): 平移/缩放过程中触发。
onMoveEnd(event, viewport): 停止平移/缩放时触发。
onSelectionChange({ nodes, edges }): 选中项（节点或边）发生变化时触发。
onNodesDelete(nodes): 删除节点前触发。
onEdgesDelete(edges): 删除边前触发。
onDrop(event): 拖拽外部元素到图表区域时触发 (用于实现拖拽添加节点)。

这些回调函数作为 props 传递给 <ReactFlow> 组件，让您可以监听并响应图表上的各种用户行为，实现复杂的交互逻辑。

3. 高级概念与定制

除了上述核心概念，React Flow 还提供了强大的定制能力：

自定义节点 (Custom Nodes): 您可以创建自己的 React 组件来渲染节点。这允许您在节点中包含更复杂的 UI、表单元素、图表或其他 React 内容。通过 nodeTypes prop 将您的组件映射到特定的节点 type。
自定义边 (Custom Edges): 您也可以创建自定义组件来渲染边，以实现特殊的视觉效果或交互。通过 edgeTypes prop 将您的组件映射到特定的边 type。
布局 (Layouting): 虽然 React Flow 本身不包含自动布局算法，但您可以结合外部布局库（如 dagre, elkjs 等）来计算节点的位置，然后将计算出的位置更新到节点状态中，React Flow 会负责按照新位置渲染。
不可变状态 (Immutable State): React Flow 的状态更新是不可变的，这与 React 的最佳实践一致，有助于状态管理的预测性和性能优化。
无头模式 (Headless): React Flow 提供了 “无头” 版本，只提供核心逻辑和状态管理 Hook，不渲染任何 UI。这适用于需要在后端或服务器端操作图表数据的场景。

4. 快速开始

要开始使用 React Flow，您需要在 React 项目中安装它：

“`bash
npm install reactflow

或者

yarn add reactflow
“`

然后，您可以构建一个基本的图表组件：

“`jsx
import React, { useCallback } from ‘react’;
import ReactFlow, {
MiniMap,
Controls,
Background,
useNodesState,
useEdgesState,
addEdge,
} from ‘reactflow’;

import ‘reactflow/dist/style.css’; // 导入默认样式

const initialNodes = [
{ id: ‘1’, position: { x: 0, y: 0 }, data: { label: ‘Hello’ } },
{ id: ‘2’, position: { x: 0, y: 100 }, data: { label: ‘World’ } },
];

const initialEdges = [{ id: ‘e1-2’, source: ‘1’, target: ‘2’, animated: true }];

export default function MyBasicFlow() {
const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

// 处理新边连接的回调
const onConnect = useCallback((params) => setEdges((eds) => addEdge(params, eds)), [setEdges]);

return (

{/ ReactFlowProvider 通常包裹在更外层，这里简化直接使用 /}

{ / 自定义 MiniMap 节点颜色 /
if (n.type === ‘input’) return ‘blue’;
if (n.type === ‘default’) return ‘#00ff00’;
if (n.type === ‘output’) return ‘red’;
return ‘#000000’;
}}
/>

);
}
“`

请确保您的应用结构中 <MyBasicFlow /> 组件被包裹在 <ReactFlowProvider> 内部（例如，在 App.js 的顶层）。

5. 总结

React Flow 是一个强大、灵活且高性能的 React 库，它极大地简化了交互式节点图和流程图的构建。通过理解其核心概念——节点、边、句柄、视口以及如何利用 useNodesState、useEdgesState 和事件回调来管理状态和响应用户交互，您可以高效地构建各种复杂的图表应用。

从基本的拖拽连接到复杂的自定义节点和集成外部布局算法，React Flow 提供了一套完整的工具集。如果您需要在 React 应用中实现任何形式的节点图或可视化编辑器，React Flow 绝对是一个值得深入学习和使用的优秀选择。

现在，您可以开始尝试使用 React Flow，构建属于您自己的交互式图表应用了！查阅官方文档和示例是进一步学习和探索 React Flow 强大功能的最佳途径。

React Flow 介绍与核心概念 – wiki基地

深入浅出 React Flow：交互式节点图构建利器 소개 및 핵심 개념 상세 설명

1. React Flow 简介

2. 核心概念详解

2.1 ReactFlowProvider

2.2 Nodes (节点)

2.3 Edges (边/连线)

2.4 Handles (句柄)

2.5 Viewport (视口)

2.6 Controls (控制组件)

2.7 State Management (状态管理)

2.8 Callbacks / Events (回调/事件)

3. 高级概念与定制

4. 快速开始

或者

5. 总结

发表评论取消回复

深入浅出 React Flow：交互式节点图构建利器 소개 및 핵심 개념 상세 설명

1. React Flow 简介

2. 核心概念详解

2.1 ReactFlowProvider

2.2 Nodes (节点)

2.3 Edges (边/连线)

2.4 Handles (句柄)

2.5 Viewport (视口)

2.6 Controls (控制组件)

2.7 State Management (状态管理)

2.8 Callbacks / Events (回调/事件)

3. 高级概念与定制

4. 快速开始

或者

5. 总结

发表评论 取消回复

发表评论取消回复