# @barefootjs/xyflow 中文文档

规范地址：https://npmcn.com/package/%40barefootjs/xyflow/

版本：0\.40\.2
npm 元数据更新时间：2026-11-02T02:54:28.808Z
中文译文更新时间：2026-11-07T18:15:25.863Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40barefootjs/xyflow
原文对照：https://npmcn.com/package/%40barefootjs/xyflow/?lang=original
项目主页：https://github.com/piconic-ai/barefootjs#readme
源码仓库：https://github.com/piconic-ai/barefootjs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：592 kB，65 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@barefootjs/jsx \>=0\.2\.0，@barefootjs/client \>=0\.2\.0
- 首次发布：2026-05-25T02:13:29.876Z
- 最新版本发布：2026-11-02T02:54:28.472Z
- 近 30 天下载量：3232（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

用于赤脚JS的基于信号的xyflow包装器

## 安装

```sh
npm install @barefootjs/xyflow
```

也可以使用：`pnpm add @barefootjs/xyflow`、`yarn add @barefootjs/xyflow`、`bun add @barefootjs/xyflow`

## README

# @ barefootjs/ xyflow

以信号为基础的包装 [`@xyflow/system`](https://www.npmjs.com/package/@xyflow/system) 页:1 [赤脚JS](https://barefootjs.dev/)船舶 **电源层** (商店、信号钩、类型、几何辅助器、必须) 指向节奏子系统). 这个 **JSX-内在渲染器组件** (单位:千美元)`Flow`, (中文(简体) ), `Background`, (中文(简体) ), `Controls`, (中文(简体) ), `MiniMap`, (中文(简体) ), `Handle`, (中文(简体) ), `NodeWrapper`, (中文(简体) ), `SimpleEdge`在shadcn 风格的登记簿中居住,地点: [`ui/components/ui/xyflow/`](https://npmcn.com/package/ui/components/ui/xyflow/) 和船舶 通过以下方式向消费者提供服务:

```sh
bf add xyflow            # via the BarefootJS CLI
npx shadcn@latest add https://ui.barefootjs.dev/r/xyflow.json
```

此分割镜像图表图案( Q)`@barefootjs/chart` 用于公用事业, `ui/components/ui/chart/` (关于JSX部分).

## 使用量

```tsx
"use client"

import { Flow, Background, Controls, MiniMap } from "@/components/ui/xyflow"
import { useNodesState, useEdgesState } from "@barefootjs/xyflow"

const initialNodes = [
  { id: "1", position: { x: 100, y: 100 }, data: { label: "Input" } },
  { id: "2", position: { x: 350, y: 50 },  data: { label: "Transform" } },
  { id: "3", position: { x: 600, y: 125 }, data: { label: "Output" } },
]
const initialEdges = [
  { id: "e1-2", source: "1", target: "2" },
  { id: "e2-3", source: "2", target: "3" },
]

export function MyCanvas() {
  const [nodes, setNodes] = useNodesState(initialNodes)
  const [edges, setEdges] = useEdgesState(initialEdges)

  return (
    <div className="w-full h-[420px]">
      <Flow nodes={nodes()} edges={edges()}>
        <Background variant="dots" gap={20} />
        <Controls />
        <MiniMap pannable zoomable />
      </Flow>
    </div>
  )
}
```

### 自定义节点正文

默认 `<Flow>` 循环生成 `data.label ?? id` 每一个里面 `<NodeWrapper>`。要编写自定义节点机构,请挂载您自己的 `<NodeWrapper>` 作为流动儿童的例子:

```tsx
<Flow nodes={nodes()} edges={edges()}>
  <Background />
  {nodes().map((n) => (
    <NodeWrapper key={n.id} nodeId={n.id}>
      <div className="rounded-md border bg-card px-3 py-2">
        {n.data.label}
        <Handle type="target" position={Position.Left}  nodeId={n.id} />
        <Handle type="source" position={Position.Right} nodeId={n.id} />
      </div>
    </NodeWrapper>
  ))}
</Flow>
```

## 此套件导出什么

| 表面 | 项目 | 目的 |
| --- | --- | --- |
| 存储/ 状态 | `createFlowStore`, (中文(简体) ), `FlowContext` | 反应节点/边缘/视图状态 |
| 钩子 | `useFlow`, (中文(简体) ), `useViewport`, (中文(简体) ), `useNodes`, (中文(简体) ), `useEdges`, (中文(简体) ), `useNodesInitialized`, (中文(简体) ), `useStore`, (中文(简体) ), `screenToFlowPosition` | 从后代读取仓库 |
| 进行回放 | `useNodesState`, (中文(简体) ), `useEdgesState`, (中文(简体) ), `useReactFlow`, (中文(简体) ), `addEdge`, (中文(简体) ), `reconnectEdge` | 植入器的滴入助手 |
| 几何 | `computeEdgePosition`, (中文(简体) ), `getEdgePath` | 共享路径数学 `<SimpleEdge>` |
| 子系统附件 | `attachFlowSubsystems` | `<Flow>`是因为 `ref` 调用此选项 — pan / 缩放 / 键盘 / 选择矩形 / gane 单击 |
| 子系统附件 | `attachConnectionHandler`, (中文(简体) ), `attachReconnectionHandler` | `<Handle>` 并重新连接上线调节器 |
| 子系统附件 | `measureNode` | `<NodeWrapper>`调整观察员的大小 — 节点大小 + 边端点的控点边界 |
| 仅限强制 | `setupKeyboardHandlers`, (中文(简体) ), `setupNodeSelection`, (中文(简体) ), `setupSelectionRectangle`, (中文(简体) ), `initNodeResizer` | JSX没有影响 |
| 再出口 | `getBezierPath`, (中文(简体) ), `getSmoothStepPath`, (中文(简体) ), `getStraightPath`, (中文(简体) ), `getConnectedEdges`, (中文(简体) ), `getOutgoers`, (中文(简体) ), `getIncomers`, (中文(简体) ), `getNodesBounds`, (中文(简体) ), `getNodesInside`, (中文(简体) ), `getEdgeToolbarTransform`, (中文(简体) ), `Position`, (中文(简体) ), `MarkerType`, (中文(简体) ), `ConnectionMode` | 从 `@xyflow/system` |
| 类型 | `FlowProps`, (中文(简体) ), `FlowStore`, (中文(简体) ), `InternalFlowStore`, (中文(简体) ), `NodeBase`, (中文(简体) ), `EdgeBase`, (中文(简体) ), `Viewport`, (中文(简体) ), `NodeLookup`, (中文(简体) ), `EdgeLookup`, (中文(简体) ), `Connection`, (中文(简体) ), `OnConnect`, (中文(简体) ), `OnReconnect`, (中文(简体) ), `IsValidConnection`, (中文(简体) ), `HandleType`,, , , , , , , , | (见 `src/types.ts`(中文(简体) ) |

## 源头布局

```
src/
├── index.ts            re-exports the utility surface above
├── store.ts            createFlowStore + signal wiring
├── hooks.ts            useFlow / useViewport / useNodes / ...
├── context.ts          FlowContext
├── types.ts            FlowProps / FlowStore / InternalFlowStore / ...
├── constants.ts        SVG_NS / INFINITE_EXTENT / ...
├── utils.ts            misc helpers
├── edge-path.ts        computeEdgePosition / getEdgePath
├── flow-subsystems.ts  attachFlowSubsystems (panZoom + ResizeObserver + ...)
├── connection.ts       attachConnectionHandler / attachReconnectionHandler
├── selection.ts        setupKeyboardHandlers / setupSelectionRectangle / setupNodeSelection
├── node-measure.ts     measureNode (node size + handle bounds)
├── node-resizer.ts     initNodeResizer (pointer-paced resize handles)
├── compat.ts           React Flow API shims
└── __tests__/          store / compat / jsx-smoke unit tests
```

JSX-内在组件是故意的 **没有** 在这个一揽子方案中——他们 住在这里 `ui/components/ui/xyflow/index.tsx` 所以消费者 `add` 页:1 直接输入他们的应用程序,可以编辑,并拥有自己的副本 (阴影图案). 这样可以避免JSX运行时间解决头痛 来自于出版 `.tsx` 直接从工作空间包.

## 浏览器捆绑( 导入地图)

`bun run build` 还发出 `dist/xyflow.browser.min.js`:完善的无害环境管理结构 与 `@barefootjs/client`, (中文(简体) ), `@barefootjs/client/runtime` 财务报告和审定财务报表 `@barefootjs/client/reactive` 留作外部( e)`build:browser` 内 `package.json`) (中文(简体) ). 作为独立缓存的静态资产而不是 重新捆绑 xyflow 进入每个客户端条目. 用手重新捆绑需要全部三个 外部——缺少一个默默地插入了反应性的第二份副本 原始人和信号停止跨越边界传播(`fitView` 变成一个不做, `FlowContext` 读错了主人.

档案也是 `umd` 出口条件和出口条件 `unpkg` 编号 : `jsdelivr` 顶级字段,所以 `https://unpkg.com/@barefootjs/xyflow` 为它服务.

复制到客户端的旁边, 并用导入图映射 :

```sh
cp node_modules/@barefootjs/xyflow/dist/xyflow.browser.min.js public/static/components/xyflow.js
cp node_modules/@barefootjs/xyflow/dist/xyflow.browser.min.js.map public/static/components/xyflow.js.map  # optional
```

```html
<script type="importmap">
{
  "imports": {
    "@barefootjs/client":          "/static/components/barefoot.js",
    "@barefootjs/client/runtime":  "/static/components/barefoot.js",
    "@barefootjs/client/reactive": "/static/components/barefoot.js",
    "@barefootjs/xyflow":          "/static/components/xyflow.js"
  }
}
</script>
```

全部三个 `@barefootjs/client*` 在一个文件的条目点, 以便浏览器保持 单个模块实例,反应原始人共享一个 `Listener` 编号 : `Owner`。 。 。 .

-   **逃脱 `<` 在输入图JSON.** 包含 `</script>` 将关闭 `<script type="importmap">` 元素早期. 将地图动态序列化时, 替换 `<` 与 `\u003c` jSON把它解码回 `<`。 。 。 .
    
-   **添加 `crossorigin` 改为跨源 `modulepreload`**,例如指向 在 unpkg URL 而不是复制文件 :
    
    ```html
    <link rel="modulepreload" href="https://unpkg.com/@barefootjs/xyflow" crossorigin>
    ```
    
    模块 `import` 总是获取 CORS; 不 `crossorigin` 预装 不匹配,浏览器会两次获取模块。 无害 同一来源的预装.
    

## 相关

-   [`@xyflow/system`](https://www.npmjs.com/package/@xyflow/system) ——上游泛相/相相+边缘路径数学库 此包包包.

## 常见问题

### @barefootjs/xyflow 是什么？

用于赤脚JS的基于信号的xyflow包装器

### 如何安装 @barefootjs/xyflow？

在项目目录运行 npm install @barefootjs/xyflow，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@barefootjs/jsx（\>=0\.2\.0）、@barefootjs/client（\>=0\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @barefootjs/xyflow 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @barefootjs/xyflow 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @barefootjs/xyflow 可以商用吗？

@barefootjs/xyflow 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @barefootjs/xyflow 的下载量有多少？

根据 npm 官方下载统计，@barefootjs/xyflow 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,232 次，日均约 108 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @barefootjs/xyflow 还在维护吗？

最新版本 0\.40\.2 发布于 2026/11/02（5 天前）；至今共发布 112 个版本，其中过去 12 个月发布了 112 个；首次发布于 2026/05/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。