// 在 nodeTypes 中注册（在组件外部定义以避免重新渲染）
const nodeTypes = { counter: CounterNode };

// 在 ReactFlow 中使用

多个手柄

tsx
// 当节点有多个同类型手柄时使用手柄 ID

// 连接特定手柄
const edge = {
id: e1-2,
source: 1,
sourceHandle: a,
target: 2,
targetHandle: null
};

自定义边

tsx
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 };

状态管理

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

tsx
// 带变更处理器的外部状态
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)),
[]
);

nodes={nodes}
edges={edges}
onNodesChange={onNodesChange}
onEdgesChange={onEdgesChange}
/>

使用 useReactFlow

tsx
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: 新建 } });
};

return 添加节点;
}

// 使用 useReactFlow 时必须包裹在 provider 中
function App() {
return (




);
}

更新节点数据

tsx
const { updateNodeData } = useReactFlow();

// 与现有数据合并
updateNodeData(nodeId, { label: 已更新 });

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

视口与适配视图

tsx
// 初始渲染时适配

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

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

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

连接验证

tsx
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;
}, []);

常用属性参考

tsx
// 核心数据
nodes={nodes}
edges={edges}
onNodesChange={onNodesChange}
onEdgesChange={onEdgesChange}

// 自定义类型（在组件外部定义）
nodeTypes={nodeTypes}
edgeTypes={edgeTypes}

// 连接
onConnect={onConnect}
connectionMode={ConnectionMode.Loose} // 允许目标到目标连接
isValidConnection={isValidConnection}

// 视口
fitView
minZoom={0.1}
maxZoom={4}
defaultViewport={{ x: 0, y: 0, zoom: 1 }}

// 交互
nodesDraggable={true}
nodesConnectable={true}
elementsSelectable={true}
panOnDrag={true}
zoomOnScroll={true}

// 附加组件

交互 CSS 类

附加组件

参见 ADDITIONAL_COMPONENTS.md 了解 MiniMap、Controls、Background、NodeToolbar、NodeResizer。