hn-workflow-components

一个基于 React + TypeScript 的可视化工作流编排组件库，提供工作流编辑器与执行进度查看器两种模式。

✨ 功能特性

• 🎨 可视化编排 — 拖拽式节点编辑，支持画布缩放与拖拽浏览
• 🔄 撤销/重做 — 完整的操作历史栈（undo/redo）
• 🌲 分支支持 — 条件分支、并行分支、包容分支三种分支类型
• 📊 执行追踪 — 独立的进度查看器，支持节点状态着色与图例
• 🧩 物料扩展 — 可自定义节点类型、属性面板与校验规则
• 🎭 主题适配 — 支持 Ant Design 主题 token 注入与暗黑模式
• 📱 响应式画布 — 自适应缩放，支持鼠标拖拽平移

📦 安装

npm install hn-workflow-components
# 或
yarn add hn-workflow-components
# 或
pnpm add hn-workflow-components

对等依赖

请确保项目中已安装以下依赖：

npm install react react-dom antd styled-components @ant-design/icons

React 版本要求：>=17 <19

🚀 快速开始

1. 工作流编辑器

用于设计流程图，支持节点增删改、分支配置与保存发布。

import { WorkflowComponents } from 'hn-workflow-components'

function App() {
  return (
    <WorkflowComponents
      processKey="leave-approval"
      processName="请假审批流程"
      baseUrl="https://api.example.com"
      customHeaders={{
        Authorization: 'Bearer xxx',
      }}
      onSave={(data) => {
        console.log('自定义保存', data)
      }}
      onPublish={(data) => {
        console.log('自定义发布回调', data)
      }}
      onSelectMembers={async (data) => {
        console.log('自定义成员选择数据')
        await new Promise(resolve => setTimeout(resolve, 1000))
        return [{ label: 'lu', value: 'lu' }, { label: 'lu2', value: 'lu2' }]
      }}
      onSelectRoles={async () => {
        console.log('自定义角色选择数据')
        await new Promise(resolve => setTimeout(resolve, 1000))
        return [{ label: 'roleu', value: 'roleu' }, { label: 'roleu', value: 'roleu22' }]
      }}
    />
  )
}

2. 工作流查看器

用于展示流程执行进度，节点按状态着色。

import { WorkflowViewerComponents } from 'hn-workflow-components'

function App() {
  return (
    <WorkflowViewerComponents
      processKey="instance-123"
      baseUrl="https://api.example.com"
      statusColors={{
        completed: '#52c41a',
        processing: '#faad14',
        pending: '#d9d9d9',
      }}
    />
  )
}

📖 API 文档

WorkflowComponents（编辑器）

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | processKey | string | ✅ | 流程定义唯一标识 | | processName | string | ✅ | 流程显示名称 | | baseUrl | string | ✅ | 后端 API 基础地址 | | customHeaders | Record<string, string> | ❌ | 自定义请求头 | | onSave | (data: any) => void | ❌ | 保存流程处理 | | onPublish | (data: any) => void | ❌ | 发布流程处理 | | onSelectMembers | () => {label:string, value:any}[] | ❌ | 成员选择 | | onSelectRoles | () => {label:string, value:any}[] | ❌ | 角色选择 |

WorkflowViewerComponents（查看器）

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | processKey | string | ✅ | 流程实例标识（用于查询执行状态） | | baseUrl | string | ✅ | 后端 API 基础地址 | | customHeaders | Record<string, string> | ❌ | 自定义请求头 | | statusColors | StatusColors | ❌ | 自定义状态颜色 |

StatusColors

interface StatusColors {
  completed?: string // 已处理（默认 #52c41a）
  processing?: string // 处理中（默认 #faad14）
  pending?: string // 待处理（默认 #d9d9d9）
}

🧩 内置节点类型

| 节点类型 | 说明 | 在物料板显示 | |----------|------|--------------| | start | 发起人节点 | ❌ | | approver | 审批人 | ✅ | | notifier | 抄送人 | ✅ | | exclusive | 条件分支 | ✅ | | parallel | 并行分支 | ✅ | | inclusive | 包容分支 | ❌ | | subProcess | 子流程 | ✅ | | dispatcher | 分发节点 | ✅ | | message | 消息通知 | ❌ | | service | 服务节点 | ❌ | | asyncSubProcess | 异步子流程 | ❌ | | trigger | 触发器 | ❌ |

🏗️ 自定义物料与 UI

如需自定义节点内容或属性面板，可通过 materialUis 传入：

import type { IMaterialUIs } from 'hn-workflow-components'

const myMaterialUis: IMaterialUIs = {
  approver: {
    // 节点卡片内容渲染
    viewContent: (node) => (
      <div>{node.config?.approverType === 'countersign' ? '会签' : '或签'}</div>
    ),
    // 校验规则
    validate: (node, { t }) => {
      if (!node.config?.groupType) {
        return t('请选择审批人')
      }
      return true
    },
  },
}

// 在业务层封装中使用
<WorkflowComponents
  processKey="xxx"
  processName="xxx"
  baseUrl="xxx"
/>

🔌 后端接口约定

组件库内置调用以下接口，请确保后端按约定实现：

| 接口 | 方法 | 路径 | 说明 | |------|------|------|------| | 查询用户与角色 | POST | /bpmn/approval/action/queryUserAndRoleData | 获取可选审批人数据 | | 获取流程定义 | POST | /bpmn/json/getBpmnJson | 根据 processKey 获取 JSON 流程图 | | 获取执行状态 | POST | /bpmn/process/queryBpmnJsonAndNodeStatus | 获取节点执行状态 | | 获取业务表单字段 | POST | /bpmn/json/bizForm | 用于条件配置 | | 保存流程图 | POST | /bpmn/json/saveBpmnJson | 保存 JSON 流程定义 | | 发布流程图 | POST | /bpmn/json/bpmnJsonToXml | 转换为 XML 并发布 | | 查询版本历史 | POST | /bpmn/json/queryBpmnJsonVersion | 获取历史版本 |

🛠️ 本地开发

# 克隆仓库
git clone <repo-url>
cd simple-workflow

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建库
pnpm build:lib

# ESLint 检查
pnpm lint

📁 目录结构

src/
├── core/workflow-editor/    # 核心编辑器引擎
│   ├── classes/             # EditorEngine 状态管理类
│   ├── components/          # 通用 UI 组件（工具栏、表达式输入等）
│   ├── FlowEditor/          # 编辑器画布、物料板、设置面板
│   ├── ProgressViewer/      # 只读进度查看器
│   ├── nodes/               # 节点渲染组件（普通节点、分支节点等）
│   ├── interfaces/          # TypeScript 类型定义
│   ├── reducers/            # Redux 状态切片
│   ├── hooks/               # React Hooks
│   └── utils/               # 工具函数（API、UUID、颜色等）
├── demo/                    # 业务层封装（可直接使用的高阶组件）
│   ├── WorkflowEditor/      # 编辑器业务封装
│   ├── WorkflowViwer/       # 查看器业务封装
│   └── ShellContainer.tsx   # 外壳容器
├── index.ts                 # 库入口，导出 WorkflowComponents / WorkflowViewerComponents
└── App.tsx / main.tsx       # 本地调试入口

⚠️ 已知限制

• 当前仅支持 React 17/18，尚未适配 React 19
• 全局配置（baseUrl、headers）通过模块级变量存储，多实例场景下可能互相影响
• 分支节点标题硬编码截取前两个字符（如"添加条件分支" → "条件分支"），需确保 getRouteNodeName 返回格式一致
• 进度查看器尚未实现路由节点（exclusive/parallel/inclusive）的状态徽章展示

🤝 贡献

欢迎提交 Issue 与 PR。提交前请确保：

1. 代码通过 pnpm lint 检查
2. 保持与现有代码风格一致
3. 如涉及 UI 变动，请在 PR 中附截图

📄 License

MIT