Devlab Web Xyflow Usage

devlab-web-xyflow-usage

库信息

适用场景

• 需要可交互的节点-边画布（流程图、拓扑图、生命周期地图等）
• 节点需要完全自定义 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<string, unknown>;       // 传递给自定义节点的数据
}

边 (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 (
    <div className="my-node">
      <Handle type="target" position={Position.Left} />
      {/* 自定义内容 */}
      <Handle type="source" position={Position.Right} />
    </div>
  );
}

const nodeTypes = { my: MyNode };

画布配置

<ReactFlow
  nodes={nodes}
  edges={edges}
  nodeTypes={nodeTypes}
  colorMode="dark"         // 暗色主题
  fitView                  // 自动适配视口
  nodesDraggable={false}   // 禁止拖拽节点
  nodesConnectable={false} // 禁止连线
  elementsSelectable={false}
  panOnDrag={false}        // 禁止画布平移
  preventScrolling={false} // 允许页面滚动
/>

Astro + React Islands 集成

包装组件

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

<!-- client:only 跳过 SSR，适合需要确定尺寸的组件 -->
<FlowComponent client:only="react" />

<!-- client:visible 延迟加载，适合首屏不需要的组件 -->
<FlowComponent client:visible />

选型规则

@astrojs/react 版本兼容矩阵

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

错误组合症状链（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。

关键摘要：

画布控制配置速查

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

推荐输出格式

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

约束

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

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

参考文档：

• references/REFERENCE-README.md