react-flow

React Flow

概述

使用此技能，借助 React Flow（@xyflow/react v12+）构建、自定义、调试和优化交互式节点式 UI。内容涵盖从基础设置到计算流、子流和外部布局集成等高级模式。

版本和来源政策

本指南已根据 2026-09-28 的 @xyflow/react 12.12.0 版本进行审核。应用 API 前，请检查目标项目安装的版本和锁定文件；“v12+”并不意味着每个次要版本都具备所有功能。除非任务要求更改，否则请保留项目现有的状态管理和样式选择。

使用官方文档索引查找特定指南或 API 页面。对于与版本相关的行为，请查看发行说明以及已安装包的声明文件或源代码。只阅读与任务相关的参考资料。省略导入或使用 ... 的示例是集成示意，并非可独立运行的应用程序。

Agent 行为规范（请遵循以下规则）

1. 对于 v12 项目，请从 @xyflow/react 导入。如果要维护旧版项目，请继续使用其已安装版本的 API，直到迁移成为任务范围的一部分。
2. 始终导入样式表：import '@xyflow/react/dist/style.css'（替换默认视觉样式时使用 base.css）。
3. <ReactFlow> 父容器的宽度和高度必须都非零（显式设置尺寸，或使用具有尺寸的 flex/grid 布局）。
4. 将 nodeTypes 和 edgeTypes 对象定义在组件外部，或用 useMemo 包装，以防止重新渲染。
5. 对于特定于应用程序的内容或连接点，请使用自定义节点；内置节点仍适用于简单的带标签图。
6. 在自定义节点中的交互元素（输入框、按钮、选择框）上使用 nodrag 类。
7. 在自定义节点中的可滚动元素上使用 nowheel 类，以防止干扰缩放。
8. 隐藏连接点时，请使用 visibility: hidden 或 opacity: 0——切勿使用 display: none（这会破坏尺寸计算）。
9. 在节点上使用多个相同类型的连接点时，始终为其分配唯一的 id 属性。
10. 添加、移除或重新定位连接点后，请在 DOM 更新后调用 useUpdateNodeInternals，例如在 effect 中调用。
11. 更新节点/边状态时，始终创建新对象——React Flow 无法检测到直接修改。
12. 对于非简单应用，优先使用受控流。对于可编辑的受控元素，请接入 onNodesChange 和 onEdgesChange；只有在用户可以创建连接时才添加 onConnect。

前 60 秒（问题排查模板）

• 根据请求确定目标：新建流、自定义节点/边、状态管理、布局、性能、样式、端到端测试、高级模式（撤销/重做、复制/粘贴、计算流、协作），或调试。
• 检查项目中的以下信息；只有在缺失信息会影响解决方案时才询问：
  • React Flow 版本（v12+ 使用 @xyflow/react）
  • TypeScript 还是 JavaScript
  • 状态管理方式（本地状态、Zustand、Redux）
  • 预期节点数量（会影响性能策略）
  • 样式方案（CSS、Tailwind、styled-components）
• 快速分类：
  • 从旧版 reactflow 或 react-flow-renderer 迁移 -> 包名变更、导入变更、API 差异
  • 画布空白或节点缺失 -> 容器尺寸或缺少 CSS 导入
  • 边未渲染 -> 缺少连接点、缺少 CSS，或连接点使用了 display: none
  • 重新渲染或性能迟缓 -> 在组件内定义了 nodeTypes，或缺少记忆化
  • 节点无法连接 -> 缺少 onConnect 处理函数或连接点配置
  • 布局/定位 -> 集成外部布局库（dagre、elkjs）
  • 类型错误 -> Node/Edge 类型的 TypeScript 泛型模式

路由图（快速找到正确的参考资料）

• 从 reactflow 或 react-flow-renderer 迁移到 @xyflow/react v12 -> references/migration.md
• 安装、设置、第一个流程、节点/边对象 -> references/fundamentals.md
• 自定义节点组件、Handle、多个 Handle、拖动手柄 -> references/custom-nodes.md
• 自定义边组件、路径工具、边标签、标记 -> references/custom-edges.md
• 事件处理程序、回调、连接验证、选择、键盘 -> references/interactivity.md
• 受控与非受控、Zustand 集成、状态更新模式 -> references/state-management.md
• Node/Edge 类型、泛型、联合类型、类型守卫 -> references/typescript.md
• 外部布局库（dagre、elkjs、d3）、子流程、父子关系 -> references/layouting.md
• 背景、Controls、MiniMap、Panel、NodeToolbar、NodeResizer、hooks -> references/components-and-hooks.md
• 记忆化、渲染优化、主题、CSS 变量、Tailwind -> references/performance-and-styling.md
• 键盘工作流、可访问名称、焦点管理、辅助技术 -> references/accessibility.md
• 服务端渲染、初始几何信息、水合、Next.js 边界 -> references/ssr-and-hydration.md
• 常见错误、调试、边显示问题、Zustand 警告 -> references/troubleshooting.md
• Playwright 端到端测试、流程选择器、拖动/视口/连接测试 -> references/e2e-testing.md
• 撤销/重做、复制/粘贴、计算流程、动态手柄、保存/恢复、协作 -> references/advanced-patterns.md
• 通过上下文菜单添加节点、侧边栏拖放、详情面板、导出为图像 -> references/recipes.md

常见问题 -> 下一步最佳做法

• 画布空白且没有错误 -> 父容器没有高度；设置明确的 height: 100vh 或等效值。
• nodeTypes / edgeTypes 警告 -> 将对象定义移到组件主体之外，或使用 useMemo 包装。
• 边已渲染但位置错误 -> 手柄使用了 display: none；改用 opacity: 0。
• 无法与节点内的输入框交互 -> 为可交互元素添加 className="nodrag"。
• 节点在拖动后弹回 -> onNodesChange 未接入，或未正确应用更改。
• 出现连接线但未创建边 -> 缺少 onConnect 处理程序，或未调用 addEdge。
• 同一侧的多个手柄重叠 -> 使用 CSS 定位它们（top 偏移），并分配唯一的 id。
• 状态更新未反映到节点上 -> 创建了变更而非新对象；必须使用展开运算符。
• Zustand 上下文警告 -> 安装了两个版本的 @xyflow/react，或缺少 <ReactFlowProvider>。
• 子流程的子节点位置错误，并出现 “Parent node not found” 警告 -> 确保父节点在 nodes 数组中排在子节点之前。

验证清单

• 确认已导入 @xyflow/react/dist/style.css（或 base.css 和自定义样式）。
• 确认父容器的宽度和高度均不为零。
• 确认 nodeTypes / edgeTypes 是稳定引用（在组件外定义或经过记忆化）。
• 确认需要连接的自定义节点使用具有正确 type、position 和 ID 的 <Handle> 组件。
• 确认节点内的可交互元素带有 nodrag 类。
• 确认受控流程为可编辑元素接入 onNodesChange/onEdgesChange，并在启用连接创建时接入 onConnect。
• 确认状态更新会创建新的节点/边对象（不进行变更）。
• 确认为 hooks 和回调应用了 TypeScript 泛型，以确保类型安全。
• 确认对性能敏感的流程使用 React.memo 记忆化自定义节点/边组件。

对于已更改的示例，请对完整代码片段进行类型检查，并在真实浏览器中测试受影响的交互。仅编译无法验证手柄、边的几何形状、拖动或视口可见性。

References

• references/migration.md
• references/fundamentals.md
• references/custom-nodes.md
• references/custom-edges.md
• references/interactivity.md
• references/state-management.md
• references/typescript.md
• references/layouting.md
• references/components-and-hooks.md
• references/performance-and-styling.md
• references/troubleshooting.md
• references/e2e-testing.md
• references/advanced-patterns.md
• references/recipes.md
• references/accessibility.md
• references/ssr-and-hydration.md