React Flow Master

型別定義（types/flow.ts）

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

// 節點資料型別：每種節點獨立定義
export type ProcessNodeData = {
  label: string;
  status: 'idle' | 'running' | 'success' | 'error';
  config: Record<string, unknown>;
};

export type DecisionNodeData = {
  label: string;
  condition: string;
};

// 聯合型別
export type AppNodeData = ProcessNodeData | DecisionNodeData;
export type AppNode = Node<ProcessNodeData, 'process'> | Node<DecisionNodeData, 'decision'>;
export type AppEdge = Edge;

Zustand Store（store/flowStore.ts）

import { create } from 'zustand';
import { applyNodeChanges, applyEdgeChanges } from '@xyflow/react';
import type { NodeChange, EdgeChange, Connection } from '@xyflow/react';
import type { AppNode, AppEdge } from '../types/flow';

type FlowState = {
  nodes: AppNode[];
  edges: AppEdge[];
  selectedNodeId: string | null;
};

type FlowActions = {
  onNodesChange: (changes: NodeChange<AppNode>[]) => void;
  onEdgesChange: (changes: EdgeChange[]) => void;
  onConnect: (connection: Connection) => void;
  selectNode: (id: string | null) => void;
  updateNodeData: <T extends AppNode>(id: string, data: Partial<T['data']>) => void;
};

export const useFlowStore = create<FlowState & FlowActions>((set) => ({
  nodes: [],
  edges: [],
  selectedNodeId: null,

  onNodesChange: (changes) =>
    set((s) => ({ nodes: applyNodeChanges(changes, s.nodes) })),

  onEdgesChange: (changes) =>
    set((s) => ({ edges: applyEdgeChanges(changes, s.edges) })),

  onConnect: (connection) =>
    set((s) => ({
      edges: [...s.edges, { ...connection, id: crypto.randomUUID() }],
    })),

  selectNode: (id) => set({ selectedNodeId: id }),

  updateNodeData: (id, data) =>
    set((s) => ({
      nodes: s.nodes.map((n) =>
        n.id === id ? { ...n, data: { ...n.data, ...data } } : n
      ),
    })),
}));

Custom Node 模板（nodes/ProcessNode.tsx）

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

function ProcessNode({ data, selected }: NodeProps<ProcessNodeData>) {
  return (
    <div className={`process-node ${selected ? 'selected' : ''}`}>
      <Handle type="target" position={Position.Left} />
      <div className="node-header">{data.label}</div>
      <div className={`node-status status-${data.status}`}>{data.status}</div>
      <Handle type="source" position={Position.Right} />
    </div>
  );
}

export default memo(ProcessNode);

nodeTypes 集中管理（nodes/index.ts）

import { memo } from 'react';
import ProcessNode from './ProcessNode';
import DecisionNode from './DecisionNode';

// 在模組層宣告，不在元件 render 內！
export const nodeTypes = {
  process: ProcessNode,
  decision: DecisionNode,
} as const;

主畫布（FlowCanvas.tsx）

import { ReactFlow, Background, Controls, MiniMap } from '@xyflow/react';
import '@xyflow/react/dist/style.css';
import { nodeTypes } from './nodes';
import { edgeTypes } from './edges';
import { useFlowStore } from '../../store/flowStore';

export function FlowCanvas() {
  const { nodes, edges, onNodesChange, onEdgesChange, onConnect } = useFlowStore();

  return (
    <ReactFlow
      nodes={nodes}
      edges={edges}
      nodeTypes={nodeTypes}
      edgeTypes={edgeTypes}
      onNodesChange={onNodesChange}
      onEdgesChange={onEdgesChange}
      onConnect={onConnect}
      fitView
    >
      <Background />
      <Controls />
      <MiniMap />
    </ReactFlow>
  );
}

自動布局（useFlowLayout.ts）

import dagre from '@dagrejs/dagre';
import { useCallback } from 'react';
import { useReactFlow } from '@xyflow/react';
import { useFlowStore } from '../store/flowStore';

const NODE_WIDTH = 180;
const NODE_HEIGHT = 60;

export function useFlowLayout() {
  const { fitView } = useReactFlow();
  const { nodes, edges } = useFlowStore();

  const applyLayout = useCallback((direction: 'LR' | 'TB' = 'LR') => {
    const g = new dagre.graphlib.Graph().setDefaultEdgeLabel(() => ({}));
    g.setGraph({ rankdir: direction, ranksep: 80, nodesep: 40 });

    nodes.forEach((n) => g.setNode(n.id, { width: NODE_WIDTH, height: NODE_HEIGHT }));
    edges.forEach((e) => g.setEdge(e.source, e.target));

    dagre.layout(g);

    const layoutedNodes = nodes.map((n) => {
      const { x, y } = g.node(n.id);
      return { ...n, position: { x: x - NODE_WIDTH / 2, y: y - NODE_HEIGHT / 2 } };
    });

    useFlowStore.setState({ nodes: layoutedNodes });
    setTimeout(() => fitView({ duration: 400 }), 0);
  }, [nodes, edges, fitView]);

  return { applyLayout };
}

效能最佳實踐

常見陷阱與解法

// ❌ 錯誤：在 render 內定義 nodeTypes（每次重新渲染都會重建）
function App() {
  const nodeTypes = { process: ProcessNode }; // 每次 render 新物件！
  return <ReactFlow nodeTypes={nodeTypes} />;
}

// ✅ 正確：模組層宣告
const nodeTypes = { process: ProcessNode };
function App() {
  return <ReactFlow nodeTypes={nodeTypes} />;
}

// ❌ 在 Custom Node 內直接 setState（破壞資料流）
function ProcessNode({ id }) {
  const store = useFlowStore();
  store.nodes = []; // 直接修改！
}

// ✅ 透過 store action 更新
function ProcessNode({ id, data }) {
  const updateNodeData = useFlowStore((s) => s.updateNodeData);
  return <input onChange={(e) => updateNodeData(id, { label: e.target.value })} />;
}

Hook 效能層級選擇

進階資源

• 完整 API Props/Hooks/Utils/Types 快查表請見 api-reference.md
• 詳細模式（自訂 Edge、動態節點新增、Undo/Redo、序列化）請見 patterns.md