用途
reactflow-expert 用于辅助开发者使用 ReactFlow v12 构建 DAG 可视化,重点是带自定义代理节点的流程图,并支持 ELKjs 自动布局、Zustand 状态管理和实时执行状态更新。资料将其定位为 ReactFlow 专用技能:交互式、可实时更新的节点-边图可视化,而非静态图或普通图表。
主要能力
技能以决策点形式组织工程判断:
- 状态管理策略:节点数 ≤ 50 时建议 useNodesState/useEdgesState,超过则用 Zustand store;需实时更新时加入 WebSocket;多组件访问用全局 store;复杂交互加 updateNodeData、bulkUpdate 等 action。
- 布局算法选择:少于 20 节点用 layered + direction=DOWN;20–100 节点用 layered + RIGHT;超过 100 节点用 stress;高度连通(边数 > 节点数 2 倍)用 force。按视口宽高比选择方向。
- 自定义节点复杂度:仅状态与名称可用内置节点加样式;3–5 字段用简单自定义节点;6 以上字段或嵌套数据用可折叠分区;含交互控件需加 nodrag 类。
- 实时同步策略:频率 < 1s 用 WebSocket 乐观更新;1–10s 用批量 WebSocket;> 10s 用 HTTP 轮询;用户触发用刷新按钮。数据量方面,完整 DAG < 1MB 可发送全量状态,更大则发送增量或按视口加载。
故障模式
资料列出五类典型问题及修复:无限重渲染(nodeTypes 定义在组件体内,需外置或 useMemo)、状态更新失效(避免原地修改对象,需展开新对象)、布局抖动(仅在拓扑变化时运行 ELK 布局)、句柄定位错配(v12 使用 positionAbsoluteX/positionAbsoluteY 而非 v11 的 xPos/yPos)、拖拽干扰(节点内按钮输入加 className="nodrag")。
使用方式示例
资料给出完整示例流程:先创建带 WebSocket 集成的 Zustand store(onNodesChange/onEdgesChange 调用 applyNodeChanges/applyEdgeChanges,updateNodeData 通过 map 生成新对象);再用 useDAGStream 处理 node_status 与 topology_change 消息,前者只更新数据、后者才触发重新布局;然后用 useAutoLayout 按节点数选择 stress 或 layered 算法,传入 measured 尺寸防止布局跳动,并 requestAnimationFrame 后再 fitView;最后定义组件外的 nodeTypes 与 AgentNode,并按状态渲染状态点、进度条和带 nodrag 的按钮。
适用场景
适合构建展示代理执行状态的实时工作流看板、需要自动布局的较大规模 DAG,以及含交互控件和状态着色的自定义节点图。
质量门与限制
资料给出功能验证(无控制台错误、自定义节点注册、布局耗时、WebSocket 收发、数据更新 200ms 内可见)、性能阈值(50 节点 1s 内首渲、100 节点 3s 内布局、200 节点内存低于 100MB、缩放平移 30fps)、视觉检查(边连接正确句柄、50% 缩放可读、状态色符合设计系统、控件不触发拖拽、fitView 留白合适)和无障碍要求(ARIA 标签、键盘选择、颜色状态有文字/图标替代、焦点可见、屏幕阅读器播报状态变化)。
明确不适用:静态图(用 mermaid-graph-writer)、普通柱状/折线/饼图(用 recharts、d3)、通用 React 开发、3D 可视化(用 three.js/WebGL)、移动优先触控界面、多用户协同编辑(ReactFlow 适合只读实时更新)。