React Flow 实现

快速开始

import { useCallback } from 'react';
import { ReactFlow, useNodesState, useEdgesState, addEdge } from '@xyflow/react';
import '@xyflow/react/dist/style.css';

const initialNodes = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: 'Node 1' } },
  { id: '2', position: { x: 200, y: 100 }, data: { label: 'Node 2' } },
];

const initialEdges = [{ id: 'e1-2', source: '1', target: '2' }];

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

  const onConnect = useCallback(
    (connection) => setEdges((eds) => addEdge(connection, eds)),
    [setEdges]
  );

  return (
    

      
    
  );
}

实现检查点（Implementation gates）

请按顺序执行以下检查；即使某项“看起来没问题”，也不得跳过。

1. 页面样式已加载 — 通过条件： 渲染 的代码包必须导入 @xyflow/react/dist/style.css（或等效的 CSS 构建流程），确保节点与边可见，且可交互区域（hit-targets）与视觉呈现一致。
2. useReactFlow 作用域边界 — 通过条件： 所有调用 useReactFlow() 的组件，必须是包裹 的同一棵组件树中 的后代（或你已明确拆分状态管理，并能准确指出两个根节点）。
3. nodeTypes / edgeTypes 稳定性 — 通过条件： 这两个映射对象必须为模块级常量，或通过 useMemo 创建且依赖项稳定；不得在渲染 的组件内部每次渲染都新建一个 { ... } 字面量对象。
4. 连接句柄（Handles）与边匹配 — 通过条件： 若某节点定义了多个具有相同类型（type）但不同 id 的 Handle，则所有需连接至特定句柄的边，必须显式设置 sourceHandle 或 targetHandle（或你已明确接受默认句柄解析逻辑）。

关于 MiniMap、Controls、Background、NodeToolbar 和 NodeResizer 的使用模式，请参阅 ADDITIONAL_COMPONENTS.md。

核心模式

TypeScript 类型定义

import type { Node, Edge, NodeProps, BuiltInNode } from '@xyflow/react';

// 定义带数据结构的自定义节点类型
type CustomNode = Node<{ value: number; label: string }, 'custom'>;

// 与内置节点类型合并
type MyNode = CustomNode | BuiltInNode;
type MyEdge = Edge<{ weight?: number }>;

// 在整个应用中统一使用
const [nodes, setNodes] = useNodesState(initialNodes);

自定义节点

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

// 定义节点类型
type CounterNode = Node<{ count: number }, 'counter'>;

// 始终使用 memo 包裹以提升性能
const CounterNode = memo(function CounterNode({ data, isConnectable }: NodeProps) {
  return (
    <>
      
      

        Count: {data.count}
        {/* nodrag 可防止点击按钮时触发拖拽 */}
         console.log('clicked')}>
          Increment
        
      
      
    
  );
});

// 在 nodeTypes 中注册（务必在组件外部定义，避免重复创建导致重渲染）
const nodeTypes = { counter: CounterNode };

// 在 ReactFlow 中使用

多句柄（Multiple Handles）

// 当节点存在多个同类型句柄时，应使用 handle ID 区分



// 连接时指定具体句柄
const edge = {
  id: 'e1-2',
  source: '1',
  sourceHandle: 'a',
  target: '2',
  targetHandle: null
};

自定义边

import { BaseEdge, EdgeProps, getSmoothStepPath } from '@xyflow/react';

function CustomEdge({ id, sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition, data }: EdgeProps) {
  const [edgePath, labelX, labelY] = getSmoothStepPath({
    sourceX, sourceY, sourcePosition,
    targetX, targetY, targetPosition,
  });

  return (
    <>
      
      {data?.label}
    
  );
}

const edgeTypes = { custom: CustomEdge };

状态管理

受控模式（推荐用于生产环境）

// 外部状态 + 变更处理器
const [nodes, setNodes] = useState(initialNodes);
const [edges, setEdges] = useState(initialEdges);

const onNodesChange = useCallback(
  (changes) => setNodes((nds) => applyNodeChanges(changes, nds)),
  []
);

const onEdgesChange = useCallback(
  (changes) => setEdges((eds) => applyEdgeChanges(changes, eds)),
  []
);

使用 useReactFlow

import { useReactFlow, ReactFlowProvider } from '@xyflow/react';

function FlowControls() {
  const {
    getNodes, setNodes, addNodes, updateNodeData,
    getEdges, setEdges, addEdges,
    fitView, zoomIn, zoomOut, setViewport,
    deleteElements, toObject,
  } = useReactFlow();

  const addNode = () => {
    addNodes({ id: `${Date.now()}`, position: { x: 100, y: 100 }, data: { label: 'New' } });
  };

  return Add Node;
}

// 使用 useReactFlow 时，必须由 ReactFlowProvider 包裹
function App() {
  return (
    
      
      
    
  );
}

更新节点数据

const { updateNodeData } = useReactFlow();

// 合并至现有数据
updateNodeData(nodeId, { label: 'Updated' });

// 完全替换数据
updateNodeData(nodeId, { newField: 'value' }, { replace: true });

视口（Viewport）与自动适配（Fit View）

// 初始渲染时自动适配


// 编程式控制
const { fitView, setViewport, getViewport, zoomTo } = useReactFlow();

// 仅适配指定节点
fitView({ nodes: [{ id: '1' }, { id: '2' }], duration: 500 });

// 设置精确视口
setViewport({ x: 100, y: 100, zoom: 1.5 }, { duration: 300 });

连接校验（Connection Validation）

const isValidConnection = useCallback((connection: Connection) => {
  // 禁止自连
  if (connection.source === connection.target) return false;

  // 自定义校验逻辑
  const sourceNode = getNode(connection.source);
  const targetNode = getNode(connection.target);

  return sourceNode?.type !== targetNode?.type;
}, []);

常用 Props 参考

用于交互控制的 CSS 类名

附加组件

MiniMap、Controls、Background、NodeToolbar 和 NodeResizer 的使用方式详见 ADDITIONAL_COMPONENTS.md。