Devlab Web Xyflow Usage

devlab-web-xyflow-usage

库信息

| 项 | 值 | |---|---| | 名称 | @xyflow/react (React Flow) | | GitHub | https://github.com/xyflow/xyflow | | 官方文档 | https://reactflow.dev | | npm | https://www.npmjs.com/package/@xyflow/react | | 当前版本 | ^12.11.1 | | 核心能力 | 节点-边画布、自定义节点/边类型、zoom/pan、拖拽、连线、子流程 | | 体积 | ~150KB (react + xyflow) |

适用场景

• 需要可交互的节点-边画布（流程图、拓扑图、生命周期地图等）
• 节点需要完全自定义 DOM 结构
• 需要 zoom/pan/fitView 画布控制
• 需要节点展开/折叠、点击交互
• 已有 React 19 环境

不适用场景

• 简单的时间线/甘特图 → 用 vis-timeline 或纯 CSS
• 纯静态的流程图展示 → 用 SVG/Canvas 直接画
• 需要亚像素级精度的图表 → 用 ECharts/D3

核心概念

节点 (Node)

interface Node {
  id: string;           // 唯一标识
  type: string;         // 对应 nodeTypes 中的组件名
  position: { x: number; y: number };  // 画布坐标
  data: Record;       // 传递给自定义节点的数据
}

边 (Edge)

interface Edge {
  id: string;
  source: string;       // 源节点 id
  target: string;       // 目标节点 id
  type?: string;        // 对应 edgeTypes 中的组件名
  animated?: boolean;
  style?: CSSProperties;
}

自定义节点

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

function MyNode({ data }: NodeProps) {
  return (
    
      
      {/* 自定义内容 */}
      
    
  );
}

const nodeTypes = { my: MyNode };

画布配置

Astro + React Islands 集成

包装组件

---
// Wrapper.astro
import FlowComponent from "./FlowComponent.tsx";
---

选型规则

| 场景 | 用 client:visible | 用 client:only="react" | |------|---------------------|--------------------------| | 组件需要确定的容器尺寸 | ❌ SSR 后尺寸为 0 | ✅ 跳过 SSR | | 首屏不需要展示 | ✅ 延迟加载 | ❌ 首屏加载 | | 依赖浏览器 API | ❌ SSR 会报错 | ✅ 只在浏览器执行 |

@astrojs/react 版本兼容矩阵

Astro 大版本与 @astrojs/react 存在强绑定关系，选错版本会导致 Vite 主版本冲突。

| Astro | @astrojs/react | Vite | @vitejs/plugin-react | |-------|---------------|------|---------------------| | 5.x | 4.x | 6.x | 4.x | | 6.x | 6.x | 8.x | 5.x |

错误组合症状链（Astro 5 + @astrojs/react@6）：

@astrojs/react@6 → @vitejs/plugin-react@5 → Vite 8
Astro 5.x 内置 Vite 6
两个 Vite 主版本在同一进程中冲突
  → "Missing field 'moduleType'" (builtin:vite-react-refresh-wrapper)
  → 模块图状态不一致
  → 连锁 "No cached compile metadata"（看似缓存问题，实为版本冲突）

验证方法：npm ls vite 检查是否只有一个 Vite 主版本。

踩坑经验

详见 [references/REFERENCE-PITFALLS.md](references/REFERENCE-PITFALLS.md)。

关键摘要：

| # | 问题 | 解法 | |---|------|------| | 1 | 节点内按钮点击被 XYFlow 吞掉 | 容器级 click 委托 + data-* 属性 | | 2 | pointer-events: none 内联样式覆盖不了 | CSS !important 无法覆盖内联样式 | | 3 | client:visible 导致 height: 0 | 用 client:only="react" | | 4 | 暗色主题节点不可见 | colorMode="dark" + 自定义 CSS | | 5 | 拖拽光标抓手 | panOnDrag={false} | | 6 | @astrojs/react@6 + Astro 5 报 Missing field 'moduleType' | Astro 5 必须用 @astrojs/react@4.x；v6 专为 Astro 6 设计，拉入 Vite 8 与 Astro 5 内置的 Vite 6 冲突。见上方版本兼容矩阵 | | 7 | 删除组件后 dev server 持续报 "No cached compile metadata" | ① Ctrl+C 停 server → ② taskkill /F /IM node.exe（确保端口释放）→ ③ 删 .astro/ + node_modules/.vite → ④ 冷启动。浏览器 Ctrl+Shift+R 强刷。注意：此症状也可能由 #6 的版本冲突连锁引发，先用 npm ls vite 排除版本问题 | | 8 | @dagrejs/dagre + compound nodes 报 Cannot set properties of undefined (setting 'rank') | dagre compound mode 有 bug，不能在 setEdge 中引用 group 节点 ID。解法：两阶段布局 — ① 只对叶子节点调用 dagre（{ compound: false }），② 从叶子位置反推 group 包围盒（minX/maxX/minY/maxY + padding）赋给 group 节点的 position + style.width/height | | 9 | React Flow compound nodes（parentId + extent）导致子节点重叠、group 框错位 | 不用 compound nodes。改为独立背景节点方案：group 节点不设 parentId，作为独立节点 zIndex: 0，子节点 zIndex: 1。布局引擎根据 _parent（存在 data 中）计算 group 包围盒并赋 position + style.width/height。group 节点用半透明虚线框渲染 | | 10 | 自定义节点没有 Handle，所有边静默丢弃（Couldn't create edge for source handle id: "null"） | 每个自定义节点必须显式声明 ` 组件（即使隐藏）。source 节点加 type="source"，target 节点加 type="target"，用 style={{ opacity: 0 }} 隐藏视觉但保留 DOM 连接点。**诊断技巧**：边看不到时，第一件事检查 .react-flow__edges 的宽高——为 0 就是 Handle 问题 | | 11 | html-to-image 截图 ReactFlow 画布内容不完整 | ① 临时解锁容器 width/height/overflow: visible（container + flowEl + viewportEl 三步），② 通过 getViewportForBounds 计算精确 transform，③ 强制重置 FlipCard 状态避免 backface-visibility 干扰，④ pixelRatio: 2 高清输出，⑤ finally 中恢复原始样式 | | 12 | ReactFlow 画布拦截页面纵向滚动 | zoomOnScroll={false}（禁止滚轮缩放）+ preventScrolling={false}（允许事件穿透到页面滚动）。仅靠 zoomOnScroll={false} 不够——默认 preventScrolling=true 仍会 preventDefault()` 滚轮事件 |

画布控制配置速查

嵌入式场景（ReactFlow 作为页面一部分而非全屏）的推荐配置：

| 配置 | 默认值 | 嵌入式推荐 | 说明 | |------|--------|-----------|------| | zoomOnScroll | true | false | 禁止滚轮缩放，避免与页面滚动冲突 | | preventScrolling | true | false | 允许 wheel 事件穿透到页面纵向滚动 | | zoomOnPinch | true | true | 触控板双指缩放仍可用 | | panOnDrag | true | true | 允许鼠标拖拽平移画布 | | nodesDraggable | true | 按需 | 节点是否可拖拽重排 | | nodesConnectable | true | false | 禁止用户手动连线 | | elementsSelectable | true | false | 禁止点击选中 |

推荐输出格式

执行完毕后输出极简回执：状态（✅ 成功 / ⚠️ 部分成功 / ❌ 失败）+ 关键结果（1-2 行，如操作对象、产出位置、下一步）。无需强制套用大表格。

约束

• 自定义节点内的交互元素必须用容器级事件委托，不能直接在节点内绑定 onClick
• 需要确定尺寸的容器必须用 client:only="react" 而非 client:visible
• 暗色主题下必须自定义节点背景色，XYFlow 默认只改画布背景

参考文档：references/REFERENCE-USAGE-DETAIL.md

参考文档：

• references/REFERENCE-README.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seed-forge
• Source: seed-forge/harness-ai-kit
• License: Apache-2.0
• Homepage: https://pypi.org/project/harness-ai-kit/

Install and usage instructions live in the source repository linked above.