快速上手 React Flow 非常简单。它本质上是一个受控组件，你只需要提供 nodes（节点）和 edges（边）的数据，它就能渲染出流程图。

下面是一个从零开始的入门教程：

1. 安装

首先，在你的 React 项目中安装核心库：

Bash

npm install @xyflow/react

(注：React Flow 现已更名为 @xyflow/react，但大家仍习惯称其为 React Flow)

2. 基础代码结构

要运行一个最简单的流程图，你需要定义初始节点、初始连线，并设置画布容器的高度。

JavaScript

import React, { useCallback } from 'react';
import {
  ReactFlow,
  MiniMap,
  Controls,
  Background,
  useNodesState,
  useEdgesState,
  addEdge,
} from '@xyflow/react';

import '@xyflow/react/dist/style.css'; // 必须引入样式

// 1. 定义初始节点
const initialNodes = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: '你好' } },
  { id: '2', position: { x: 0, y: 100 }, data: { label: 'React Flow' } },
];

// 2. 定义初始连线
const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];

export default function App() {
  // 使用内置的 Hook 管理节点和边的状态
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  // 3. 处理连线动作
  const onConnect = useCallback(
    (params) => setEdges((eds) => addEdge(params, eds)),
    [setEdges],
  );

  return (
    // 注意：父容器必须有明确的高度，否则画布不会显示
    <div style={{ width: '100vw', height: '100vh' }}>
      <ReactFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        onConnect={onConnect}
      >
        <Controls />      {/* 左下角控制栏 */}
        <MiniMap />       {/* 右下角小地图 */}
        <Background variant="dots" gap={12} size={1} /> {/* 背景网格 */}
      </ReactFlow>
    </div>
  );
}

3. 核心概念解析

概念

描述

Nodes (节点)

对象数组。每个节点必须包含唯一的 id 和坐标 position: {x, y}。data 属性用于存放显示的文字或组件数据。

Edges (边)

对象数组。必须包含 source（起点 ID）和 target（终点 ID）。

onConnect

当用户手动从一个节点拉线到另一个节点时触发。addEdge 是内置工具函数，用于将新连线加入数组。

受控组件

onNodesChange 和 onEdgesChange 负责处理拖拽、删除节点等交互。如果不绑定这些函数，节点将无法被拖动。

4. 进阶：自定义节点 (Custom Nodes)

这是 React Flow 最强大的地方。你可以创建一个自定义组件，并告诉 React Flow 使用它。

  1. 定义组件（使用 Handle 组件定义连接点）：

    JavaScript

    import { Handle, Position } from '@xyflow/react';

function TextUpdaterNode({ data }) {
  return (
    <div style={{ background: '#fff', padding: '10px', border: '1px solid #777' }}>
      <Handle type="target" position={Position.Top} />
      <div>
        <label>输入文字: </label>
        <input onChange={(evt) => console.log(evt.target.value)} />
      </div>
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

  2. 注册并使用：

    JavaScript

    const nodeTypes = { textUpdater: TextUpdaterNode }; // 注册

const initialNodes = [
  { 
    id: 'node-1', 
    type: 'textUpdater', // 指定类型
    position: { x: 0, y: 0 }, 
    data: { value: 123 } 
  },
];

5. 建议学习路径

  1. 第一步： 跑通上面的基础代码，尝试手动修改节点坐标。

  2. 第二步： 学习如何通过按钮点击动态添加一个新节点。

  3. 第三步： 掌握自定义节点，实现在节点内部放置你自己的 UI 组件。

  4. 第四步： 学习使用 useReactFlow 钩子，从外部控制画布（如点击按钮自动缩放至全屏）。