特性

• 三种节点类型：任务节点（JOB）、判断节点（DECISION）、嵌套工作流节点（NESTED_WORKFLOW）
• 画布能力：拖拽节点、连线、编辑/查看模式切换、缩放限制（25%–200%）、连接吸附方向（水平/垂直）
• 连线样式：基础灰色连线、分支线（true/false 绿色/红色 + Y/N 标签）、选中高亮
• 编辑面板：右侧滑入面板、表单校验、保存确认
• 自动布局：Dagre 层次布局，支持横向/纵向
• 撤销重做：支持可配置步数历史记录（默认 50 步）
• 右键菜单：添加节点、复制粘贴
• 快捷键：Delete、Ctrl+Z/Y、Ctrl+C/V、Ctrl+A、Ctrl+D、Escape
• 视图模式：节点状态展示、运行动画、执行详情 Tooltip
• 增强功能：小地图导航、节点搜索筛选、可选内嵌工具栏
• 国际化：中英文（zh-CN / en-US），默认中文

安装

npm install power-workflow-next

快速开始

import {
  WorkflowCanvas,
  useWorkflowStore,
  layoutNodes,
  NodeType,
  NodeStatus,
} from 'power-workflow-next';
import 'power-workflow-next/style.css';

const initialNodes = [
  {
    id: '1',
    type: 'JOB',
    position: { x: 0, y: 0 },
    data: {
      label: '数据清洗任务',
      type: NodeType.JOB,
      jobId: 1001,
      enable: true,
    },
  },
];

const initialEdges = [];

function App() {
  const { nodes, edges, setNodes, setEdges } = useWorkflowStore();

  return (
    <div className="w-full h-screen">
      <WorkflowCanvas nodes={nodes} edges={edges} mode="edit" defaultLocale="zh-CN" />
    </div>
  );
}

API 文档

WorkflowCanvas Props

组件接受 WorkflowNextProps，继承 React Flow 的常用画布能力，主要属性如下：

| 属性 | 类型 | 默认值 | 说明 | | -------------------- | ------------------------ | --------- | ---------------------- | | nodes | WorkflowNode[] | [] | 节点数据 | | edges | WorkflowEdge[] | [] | 连线数据 | | mode | 'edit' \| 'view' | 'edit' | 编辑/视图模式 | | defaultLocale | 'zh-CN' \| 'en-US' | 'zh-CN' | 默认语言 | | onNodesChange | function | - | 节点变化回调 | | onEdgesChange | function | - | 连线变化回调 | | onConnect | function | - | 连线连接回调 | | onNodeDataChange | function | - | 节点数据变化回调 | | onValidationError | (errors: unknown[]) => void | - | 校验失败回调 | | connectSnapDirection | 'horizontal' \| 'vertical' | - | 连接吸附方向 | | showToolbar | boolean | - | 是否在画布上方显示工具栏 | | jobOptions | WorkflowReferenceOption[] | - | 任务下拉选项（编辑面板） | | workflowOptions | WorkflowReferenceOption[] | - | 工作流下拉选项（嵌套节点） | | onAutoLayout | function | - | 自动布局回调 | | onAddNode | function | - | 添加节点回调 | | onExport / onImport | function | - | 导出/导入回调 | | showMinimap / onToggleMinimap | boolean / function | - | 小地图显示与切换 | | undoableActions | number | 50 | 撤销历史步数上限 |

数据结构

WorkflowNodeData

interface WorkflowNodeData {
  label: string;
  type: NodeType;
  status?: NodeStatus;
  instanceId?: string;
  execution?: ExecutionInfo;

  jobId?: string | number;
  enable?: boolean;
  skip?: boolean;
  timeout?: number;
  params?: string;
  condition?: string;
  targetWorkflowId?: string | number;

  /** 判断节点执行结果，仅 DECISION 节点在运行后存在 */
  result?: 'true' | 'false';
  /** 因控制节点而被禁用，仅视图/运行态 */
  disableByControlNode?: boolean;
}

NodeType

enum NodeType {
  JOB = 'JOB',
  DECISION = 'DECISION',
  NESTED_WORKFLOW = 'NESTED_WORKFLOW',
}

NodeStatus

enum NodeStatus {
  WAITING = 1,
  RUNNING = 3,
  FAILED = 4,
  SUCCESS = 5,
  CANCELED = 6,
  STOPPED = 10,
}

工具函数

import {
  layoutNodes,           // Dagre 自动布局
  detectCycle,           // 循环依赖检测
  checkDecisionNodeExits, // 判断节点出口校验
  exportToJSON,          // 导出为 JSON
  importFromJSON,        // 从 JSON 导入
  generateNodeId,        // 生成节点 ID
  generateEdgeId,        // 生成连线 ID
  createDefaultNodeData, // 创建默认节点数据
  deepClone,             // 深拷贝
} from 'power-workflow-next';

import {
  assignOptimalHandles,   // 分配最优连接把手
  getOptimalHandlesForEdge,
  getSnapHandlesForEdge,
  normalizeConnectionDirection,
} from 'power-workflow-next';

// 自动布局
const newNodes = layoutNodes(nodes, edges, { direction: 'horizontal' });

// 循环检测
const cycleError = detectCycle(nodes, edges);

// 导出 / 导入
const json = exportToJSON(nodes, edges);
const { success, data, error } = importFromJSON(jsonString);

校验器

import {
  required,
  minLength,
  maxLength,
  range,
  pattern,
  json,
  condition,
  positiveInteger,
  nodeName,
  composeValidators,
  useValidators,
} from 'power-workflow-next';

Web Component 使用方式

power-workflow-next 支持作为 Web Component 使用，可以在 Vue、原生 JS 等任何前端环境中使用。

安装依赖

# 安装核心包
npm install @echo009/power-workflow-next

# 安装 React 依赖（Web Component 需要）
npm install react react-dom @xyflow/react

Vue 3 中使用

<template>
  <power-workflow-canvas
    ref="canvasRef"
    mode="edit"
    locale="zh-CN"
    show-toolbar
    @nodeschange="handleNodesChange"
    @edgeschange="handleEdgesChange"
    @connect="handleConnect"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import '@echo009/power-workflow-next/web-component';
import '@echo009/power-workflow-next/style.css';

const canvasRef = ref(null);

onMounted(() => {
  // 设置数据
  canvasRef.value.nodes = [
    { id: '1', type: 'JOB', position: { x: 0, y: 0 }, data: { label: '任务1', type: 'JOB' } }
  ];
  canvasRef.value.edges = [];
});

function handleNodesChange(e) {
  console.log('Nodes changed:', e.detail);
}

async function save() {
  const data = canvasRef.value.getGraphData();
  // 保存到后端
}
</script>

<style>
power-workflow-canvas {
  display: block;
  width: 100%;
  height: 600px;
}
</style>

原生 JS 中使用

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
</head>
<body>
  <power-workflow-canvas id="canvas" mode="edit"></power-workflow-canvas>

  <script type="module">
    import '@echo009/power-workflow-next/web-component';
    import '@echo009/power-workflow-next/style.css';

    const canvas = document.getElementById('canvas');

    // 设置数据
    canvas.nodes = [
      { id: '1', type: 'JOB', position: { x: 0, y: 0 }, data: { label: '任务1', type: 'JOB' } }
    ];

    // 监听事件
    canvas.addEventListener('nodeschange', (e) => {
      console.log('Changed:', e.detail);
    });

    // 获取数据
    function save() {
      const data = canvas.getGraphData();
      console.log('Save:', data);
    }
  </script>
</body>
</html>

Web Component API 参考

HTML 属性 (Attributes)

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | mode | 'edit' \| 'view' | 'edit' | 编辑/查看模式 | | locale | 'zh-CN' \| 'en-US' | 'zh-CN' | 语言 | | show-toolbar | boolean | false | 显示工具栏 | | show-minimap | boolean | true | 显示小地图 | | connect-snap-direction | 'horizontal' \| 'vertical' | 'horizontal' | 连线吸附方向 |

JS 属性 (Properties)

| 属性 | 类型 | 说明 | |------|------|------| | nodes | WorkflowNode[] | 节点数据 | | edges | WorkflowEdge[] | 边数据 | | jobOptions | WorkflowReferenceOption[] | 任务选项列表 | | workflowOptions | WorkflowReferenceOption[] | 工作流选项列表 | | undoableActions | number | 撤销历史步数（默认 50） |

事件 (Events)

| 事件名 | detail 类型 | 说明 | |--------|-------------|------| | nodeschange | NodeChange[] | 节点变化 | | edgeschange | EdgeChange[] | 边变化 | | connect | Connection | 新连接 | | autolayout | { direction: string } | 自动布局请求 | | addnode | { type: NodeType, position?: { x, y } } | 添加节点请求 | | export | {} | 导出请求 | | import | {} | 导入请求 |

方法 (Methods)

| 方法 | 返回值 | 说明 | |------|--------|------| | getGraphData() | { nodes: WorkflowNode[], edges: WorkflowEdge[] } | 获取当前图数据（深拷贝） | | fitView() | void | 自适应视图 | | zoomIn() | void | 放大 | | zoomOut() | void | 缩小 | | setNodes(nodes) | void | 设置节点 | | setEdges(edges) | void | 设置边 |

开发

# 安装依赖
npm install

# 启动开发服务器（运行 playground 演示）
npm run dev

# 构建库
npm run build:lib

# 运行测试
npm run test

# 类型检查
npm run typecheck

# 代码检查
npm run lint

发布

本项目使用 GitHub Actions 做自动发布，推送版本标签即可触发。

发布步骤

1. 更新版本号（按需选一种）

   • 手动改 package.json 里的 version
   • 或使用 npm version patch|minor|major（会打 tag，注意与下面步骤合并）

2. 打标签并推送

   git tag v1.0.1
   git push origin v1.0.1

   推送以 v 开头的标签（如 v1.0.1）后，Actions 会自动：构建、跑测试、创建 GitHub Release；若已按下方配置启用，则同时发布到 npm。

配置 NPM 发布（可选）

若需自动发布到 npm，在仓库 Settings → Secrets and variables → Actions 中配置：

• Secrets 新增 NPM_TOKEN：npm 访问令牌（npmjs.com → Account → Access Tokens，建议选 Automation）。
• Variables 新增 PUBLISH_TO_NPM，值为 true。

两者都配置后，推送 tag 时才会执行 npm publish。未配置或未设 PUBLISH_TO_NPM 时，仅构建、测试并创建 GitHub Release。

项目结构

power-workflow-next/
├── src/
│   ├── components/
│   │   ├── WorkflowCanvas/   # 画布主组件
│   │   ├── nodes/            # 节点组件（JobNode、DecisionNode、NestedWorkflowNode）
│   │   ├── edges/            # 连线组件
│   │   ├── panels/           # 编辑面板与表单（EditorPanel、*Form、表单控件）
│   │   ├── toolbar/          # 工具栏
│   │   └── common/           # 通用组件（小地图、Tooltip、右键菜单等）
│   ├── contexts/             # React 上下文（LocaleContext）
│   ├── hooks/                # 自定义 Hooks（快捷键、搜索、国际化）
│   ├── stores/               # Zustand 状态管理
│   ├── utils/                # 工具函数（布局、校验、工作流、边把手）
│   ├── types/                # TypeScript 类型
│   ├── locales/              # 国际化
│   ├── styles/               # 样式文件（含 Shadow DOM 样式注入模块）
│   └── web-component.tsx     # Web Component 封装入口
├── tests/
│   ├── setup.ts              # 测试环境配置
│   └── unit/                 # 单元测试
│       ├── components/       # 组件测试（含 nodes、edges）
│       ├── stores/           # 状态管理测试
│       ├── utils/            # 工具函数测试
│       └── web-component.test.ts  # Web Component 测试
├── examples/
│   └── vue-integration/      # Vue 3 集成示例
│       └── src/
│           └── components/
│               └── WorkflowDemo.vue
├── playground/               # 本地演示与调试（npm run dev 入口）
├── docs/                     # 文档与设计说明
│   └── plans/                # 实现计划与设计文档
├── dist/                     # 构建产物
│   ├── index.mjs             # React 组件入口
│   ├── web-component.mjs     # Web Component 入口
│   └── power-workflow-next.css
├── package.json
├── vite.config.ts
└── tsconfig.json