• 前端
• UI组件
• 图表库

导读

本指南以 examples/README.md 为核心，完整梳理 xyflow 仓库中面向功能开发与 E2E 测试的示例体系：包括基于 Vite 的 React Flow 示例应用、基于 SvelteKit 的 Svelte Flow 示例应用，以及专用于 SSR（服务端渲染）验证的 Astro 应用。读完本文，你将掌握每个示例应用的启动方式、如何为正在开发的新功能添加对应示例与路由、如何通过generic-tests配置驱动 Playwright 跨框架 E2E 测试，并理解示例代码与 packages/react 和 packages/svelte 等源码包之间的关联。

示例仓库的定位与整体结构

xyflow 仓库中的examples目录不是面向最终用户的演示站点，而是内部用于功能开发和 E2E 测试的"测试床"。仓库根目录的 examples/README.md 开宗明义地说明："These examples are used for feature development and E2E testing."（这些示例用于功能开发与 E2E 测试）。

该目录下包含三个彼此独立的示例工程：

三者共享同一套跨框架的 E2E 测试策略：测试实现放在tests/playwright，而测试用例所依赖的 Flow 配置则定义在各个示例工程内部。仓库中 E2E 测试的完整文档位于 tests/playwright/README.md。

从依赖关系看，各示例工程通过 pnpm workspace 直接引用源码包。例如 examples/react/package.json 中声明了"@xyflow/react": "workspace:*"和"@xyflow/system": "workspace:*"，examples/svelte/package.json 中声明了"@xyflow/svelte": "workspace:^"。这意味着示例代码始终运行在仓库当前源码版本之上，开发者在packages中的改动会即时反映到示例应用中，这也是"开发即测试"工作流能够成立的基础。

React Flow 示例应用（examples/react）

启动本地开发服务器

examples/react/README.md 给出了最简单的启动方式：

pnpm dev

该命令实际执行的是 Vite 开发服务器：examples/react/package.json 中定义"dev": "vite --port 3000 --open --host"，即固定端口3000、自动打开浏览器并监听所有主机地址。其余可用脚本包括：

• pnpm serve：仅启动静态服务器（vite serve --port 3000），供 E2E 测试使用；
• pnpm build：执行vite build构建生产版本；
• pnpm preview：预览构建产物；
• pnpm test：依次运行组件测试与 E2E 测试（test-component+test-e2e）；
• pnpm test:dev：打开 Cypress 交互界面；
• pnpm test-e2e：通过start-server-and-test先启动静态服务器，再以 headless 模式运行 Cypress E2E。

添加一个新的示例 Flow

功能开发是围绕src/examples目录进行的，README 给出了两步添加流程：

1. 在 examples/react/src/examples 下创建新的文件夹与 Flow 实现；
2. 在 examples/react/src/App/routes.ts 中注册新路由。

examples/react/src/App/routes.ts 是路由注册表：顶部批量import了每个示例组件，中部定义了IRoute接口（name、path、component），底部通过routes数组将每个示例映射到形如basic、draghandle、save-restore、validation的 URL 路径。当前仓库中已注册了数十个示例，覆盖节点（CustomNode、NodeToolbar、NodeResizer、DetachedHandle）、边（Edges、EdgeToolbar、EdgeRouting、ReconnectEdge、CancelConnection）、Hooks（useConnection、useNodesData、useKeyPress、useOnSelectionChange、useReactFlow、useUpdateNodeInternals）、状态管理（Redux、SetNodesBatching、ControlledUncontrolled）以及交互（DragNDrop、TouchDevice、InteractiveMinimap、ZIndexMode、Middlewares、DevTools）等主题。

以Basic为例：入口组件位于 examples/react/src/examples/Basic/index.tsx，在路由表中注册为{ name: 'Basic', path: 'basic', component: Basic }，开发时即可通过http://localhost:3000/basic访问。

添加新的 E2E 测试 Flow

与功能示例不同，E2E 测试面向的是src/generic-tests目录下按"配置驱动"方式定义的 Flow。README 中特别强调：

Adding a new configuration file automatically adds a new route underhttp://localhost:3000/tests/generic/$foldername/$filename.

即新增一个配置文件就会自动获得一条新路由，无需手动注册。其实现机制在 examples/react/src/generic-tests/index.tsx 中：

import { useLocation } from 'react-router-dom'; import Flow from './Flow'; const flowConfigs = import.meta.glob<FlowConfig>('./**/*.ts', { eager: true, import: 'default' }); export default () => { const location = useLocation(); const path = `.${location.pathname.replace('/tests/generic', '')}.ts`; const flowConfig = flowConfigs[path]; if (!flowConfig) { return `404: This route doesn't exists.`; } return <Flow flowConfig={flowConfig} />; };

这里借助 Vite 的import.meta.glob在构建期将generic-tests目录下所有.ts文件批量收集为FlowConfig，再把 URL 路径（如/tests/generic/pane/general）映射为对应配置文件（./pane/general.ts）。配置文件不存在时返回 404 提示，存在则渲染通用 examples/react/src/generic-tests/Flow.tsx 组件。

通用Flow组件把FlowConfig中的flowProps展开为<ReactFlow>的 props，并依次挂载Controls、Panel、MiniMap、Background（分别受controlsProps、panelProps、minimapProps、backgroundProps控制）。同时它内部维护受控的 nodes/edges 状态：onNodesChange走applyNodeChanges、onEdgesChange走applyEdgeChanges、onConnect走addEdge——这是 examples/react/src/generic-tests/Flow.tsx 中最核心的三行受控逻辑，与 examples/react/src/examples/Basic/index.tsx 等常规示例的写法一致。

Svelte Flow 示例应用（examples/svelte）

examples/README.md 指出 Svelte 示例是一个SvelteKit App。其启动方式同样为：

pnpm dev

examples/svelte/package.json 中的脚本基于 SvelteKit（vite dev），并额外提供了check（svelte-kit sync+svelte-check）、lint、format等开发辅助命令。依赖方面它引入了 Svelte 5（svelte: ^5.55.5）与@xyflow/svelte，同时包含@dagrejs/dagre以支持布局类示例。

Svelte 示例的 E2E Flow 配置位于 examples/svelte/src/generic-tests，包含与 React 侧平行的目录结构（如edges/general.ts、pane/general.ts、node-toolbar/components/ToolbarNode.svelte、nodes/components/DragHandleNode.svelte）。配置通过 SvelteKit 的动态路由 examples/svelte/src/routes/tests/generic/[topic]/[example]/+page.ts 加载：

import { error } from '@sveltejs/kit'; const flowConfigs = import.meta.glob<FlowConfig>('/src/generic-tests/**/*.ts', { eager: true, import: 'default' }); export function load({ params }) { const flowConfig = flowConfigs[`/src/generic-tests/${params.topic}/${params.example}.ts`]; if (!flowConfig) { throw error(404, 'Not found'); } return { flowConfig }; }

与 React 侧一样，这里也使用import.meta.glob批量收集配置，并将 URL 中的[topic]/[example]段映射为src/generic-tests下的具体文件；配置不存在时通过 SvelteKit 的error(404)返回 404。得益于同一套FlowConfig结构与相同的目录组织，同一份测试用例（如pane/general）可以在 React 与 Svelte 两个框架上运行几乎一致的 Flow，这正是 xyflow 跨框架 E2E 测试的基石。

Astro 示例应用（examples/astro-xyflow）

examples/README.md 将 examples/astro-xyflow 定位为"Astro App used for SSR testing"，即专门用于服务端渲染测试的轻量应用。

examples/astro-xyflow/README.md 说明它是一个"Tiny app for testing React Flow and Svelte Flow with Astro"，启动方式同样是：

pnpm dev

从目录结构看，examples/astro-xyflow/src/components 下同时存在ReactFlowExample、ReactFlowInitialExample、SvelteFlowExample、SvelteFlowInitialExample四组组件，并由 examples/astro-xyflow/src/pages/index.astro 统一承载。这种"React + Svelte 双框架共存于同一个 Astro 页面"的结构，正是为了验证 xyflow 的库组件在 Astro 的 islands（客户端岛屿）架构下能否在服务端正常渲染、序列化并水合，从而覆盖 SSR 兼容性这一关键场景。

跨框架 Playwright E2E 测试（tests/playwright）

安装与运行

examples/README.md 将 E2E 测试的详细文档指向仓库根的 tests/playwright，其使用说明位于 tests/playwright/README.md：

cd tests/playwright # 确认位于正确目录 pnpm install # 安装 node 依赖 npx playwright install # 按提示安装浏览器

运行测试的命令：

pnpm run test:react # headless 运行全部 React 测试 pnpm run test:react:ui # UI 模式运行 React 测试，便于调试 pnpm run test:svelte # headless 运行全部 Svelte 测试 pnpm run test:svelte:ui # UI 模式运行 Svelte 测试，便于调试

这些脚本定义在 tests/playwright/package.json 中，例如"test:react": "FRAMEWORK=react pnpm exec playwright test -c playwright.react.config.ts"，即通过环境变量FRAMEWORK区分框架，并分别使用 tests/playwright/playwright.react.config.ts（端口 3000）与 tests/playwright/playwright.svelte.config.ts 两份配置；ui后缀版本在命令后追加--ui参数以进入 Playwright UI 模式。

创建新的测试 Flow

E2E 测试的 Flow 实现位于各示例工程的src/generic-tests下。创建流程分为两步。

第一步：创建或复用 Flow 配置。在examples/{framework}/src/generic-tests下新建文件，以"配置对象 +satisfies FlowConfig"的方式声明将应用到组件上的所有 props（tests/playwright/README.md 给出的示例）：

// NewFolder/NewTest.ts export default { flowProps: { minZoom: 0.25, maxZoom: 4, fitView: true, nodes: [ { id: '1', data: { label: '1' }, position: { x: 0, y: 0 }, type: 'input', }, { id: '2', data: { label: '2' }, position: { x: -100, y: 100 }, }, { id: '3', data: { label: '3' }, position: { x: 100, y: 100 }, }, ], edges: [ { id: 'first-edge', source: '1', target: '2' }, { id: 'second-edge', source: '1', target: '3' }, ], }, backgroundProps: { /* ... */ }, panelProps: { /* ... */ }, minimapProps: { /* ... */ }, controlsProps: { /* ... */ }, } satisfies FlowConfig;

仓库中真实存在的示例见 examples/react/src/generic-tests/pane/general.ts：配置了minZoom: 0.25、maxZoom: 4、fitView: true以及 1 个 input 节点 + 2 个普通节点、2 条边的三节点拓扑；类似的配置还存在于 examples/react/src/generic-tests/edges/general.ts、examples/svelte/src/generic-tests/nodes/general.ts 等文件中。

README 特别用:warning:强调：目录与文件名直接决定测试用例的路由。以上示例会生成http://localhost:3000/tests/generic/newDirectory/newTest（其中 3000 是 React 示例应用的端口，其他框架可能不同）。这一行为与 examples/react/src/generic-tests/index.tsx 和 SvelteKit 动态路由的路径映射机制完全吻合。

第二步：编写 Playwright 测试用例。将新的测试文件放到 tests/playwright/e2e 下。当前仓库已包含background.spec.ts、edges.spec.ts、node-toolbar.spec.ts、nodes.spec.ts、pane.spec.ts、props.spec.ts等规格文件，以及 tests/playwright/e2e/constants.ts（测试 URL 常量）与 tests/playwright/e2e/utils.ts（公共工具函数），可作为新用例的编写范式。

FlowConfig 的字段约定

综合 README 示例与 examples/react/src/generic-tests/Flow.tsx 的实际消费方式，FlowConfig包含以下字段：

值得注意的设计是：flowProps中的nodes、edges只是初始值，真正的运行状态由Flow组件内的useState接管，并通过applyNodeChanges/applyEdgeChanges/addEdge维持受控更新。这意味着 E2E 测试既能以稳定的初始拓扑启动，又能完整验证拖拽、连接等交互行为对节点与边状态的影响。

从示例到源码：示例体系与核心包的呼应

示例工程并非孤立存在，它与packages下的源码包形成"用例 — 实现"的呼应关系：

• 示例中使用的ReactFlow、applyNodeChanges、applyEdgeChanges、addEdge、Controls、MiniMap、Background、Panel等 API 的实现位于 packages/react/src（如容器组件 packages/react/src/container/ReactFlow/index.tsx、状态变更工具 packages/react/src/utils/changes.ts 与附加组件目录 packages/react/src/additional-components）；
• Svelte 侧的对应实现位于 packages/svelte/src/lib，其中 packages/svelte/src/lib/container/SvelteFlow、packages/svelte/src/lib/plugins（Background、Controls、MiniMap、NodeToolbar 等）与 React 侧结构一一对应；
• 两个框架共享的底层交互逻辑（拖拽、缩放、连线、调整尺寸）沉淀在 packages/system/src 的xydrag、xypanzoom、xyhandle、xyresizer等模块中，这正是 examples/react/package.json 同时依赖@xyflow/react与@xyflow/system的原因。

因此，当你为某个新特性（例如一个新的自定义节点类型或一条新的交互路径）添加示例并运行 E2E 测试时，实际验证的是@xyflow/system→@xyflow/react/@xyflow/svelte→ 示例组件 的完整调用链，这也是该示例体系能够同时服务于功能开发与跨框架质量保障的根本原因。

结语

examples目录是 xyflow 仓库中连接"库源码"与"质量保障"的关键枢纽：examples/react与examples/svelte分别是 React Flow 与 Svelte Flow 的活体开发环境，examples/astro-xyflow覆盖 SSR 兼容性验证，而tests/playwright则借助FlowConfig配置驱动模式，用同一套 Flow 在两大框架上运行框架无关的 E2E 测试。理解这套"配置即路由、示例即用例"的组织方式后，无论是为新功能添加示例，还是为既有行为补充回归测试，你都能快速上手。

• 前端
• UI组件
• 图表库