@xiaoxiao6.0/flow-designer-react

v1.0.2

Published

7 months ago

流程设计器 React 适配器

0High
0Medium
0Low

xiaoxiao6.0

flow-designer react workflow approval-flow

@xiaoxiao6.0/flow-designer-react

流程设计器 React 适配器 - 基于 ReactFlow 的可视化流程编排组件

安装

npm install @xiaoxiao6.0/flow-designer-react

或使用其他包管理器：

pnpm add @xiaoxiao6.0/flow-designer-react
yarn add @xiaoxiao6.0/flow-designer-react

特性

🎨 React 18+：使用最新的 React Hooks
🚀 开箱即用：提供完整的流程设计器组件
🔄 受控组件：支持完全的状态控制
📦 轻量级：基于 ReactFlow，性能优秀
💪 TypeScript：完整的类型定义支持
🎯 可视化：拖拽式流程设计体验

快速开始

基础使用

import { FlowDesigner } from '@xiaoxiao6.0/flow-designer-react';
import { useState } from 'react';
import type { FlowConfig } from '@xiaoxiao6.0/flow-designer-react';

function App() {
  const [flowConfig, setFlowConfig] = useState<FlowConfig>({
    id: 'flow-1',
    name: '请假审批流程',
    version: '1.0.0',
    nodes: [
      {
        id: 'start-1',
        type: 'start',
        title: '发起申请',
        config: {}
      },
      {
        id: 'approval-1',
        type: 'approval',
        title: '部门经理审批',
        config: {
          approvers: ['manager1']
        }
      },
      {
        id: 'end-1',
        type: 'end',
        title: '结束',
        config: {}
      }
    ],
    edges: [
      {
        id: 'edge-1',
        source: 'start-1',
        target: 'approval-1'
      },
      {
        id: 'edge-2',
        source: 'approval-1',
        target: 'end-1'
      }
    ],
    settings: {}
  });

  return (
    <FlowDesigner
      config={flowConfig}
      onChange={setFlowConfig}
      onNodeDoubleClick={(node) => {
        console.log('双击节点:', node);
      }}
    />
  );
}

export default App;

使用 Hook

使用 useFlowDesigner hook 进行更精细的控制：

import { useFlowDesigner } from '@xiaoxiao6.0/flow-designer-react';
import { useState } from 'react';
import type { FlowConfig } from '@xiaoxiao6.0/flow-designer-react';

function App() {
  const [flowConfig, setFlowConfig] = useState<FlowConfig>({
    id: 'flow-1',
    name: '审批流程',
    version: '1.0.0',
    nodes: [],
    edges: [],
    settings: {}
  });

  const {
    config,
    nodes,
    edges,
    addNode,
    updateNode,
    removeNode,
    addEdge,
    validate
  } = useFlowDesigner({
    config: flowConfig,
    onChange: (newConfig) => {
      setFlowConfig(newConfig);
      console.log('配置已更新:', newConfig);
    }
  });

  // 添加审批节点
  const handleAddApprovalNode = () => {
    addNode({
      id: `approval-${Date.now()}`,
      type: 'approval',
      title: '审批节点',
      config: {
        approvers: ['user1']
      }
    });
  };

  // 验证流程
  const handleValidate = () => {
    const result = validate();
    if (result.valid) {
      console.log('流程验证通过');
    } else {
      console.error('验证失败:', result.errors);
    }
  };

  return (
    <div>
      <div>
        <button onClick={handleAddApprovalNode}>添加审批节点</button>
        <button onClick={handleValidate}>验证流程</button>
      </div>
      <div>节点数量: {nodes.length}</div>
      <div>连线数量: {edges.length}</div>
    </div>
  );
}

API 文档

FlowDesigner 组件

流程设计器主组件。

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | config | FlowConfig | 必填 | 流程配置对象 | | onChange | (config: FlowConfig) => void | - | 配置变化回调 | | loaders | DataLoaders | - | 数据加载器 | | nodeComponents | Record<string, ComponentType> | - | 自定义节点组件 | | formComponents | Record<string, ComponentType> | - | 自定义表单组件 | | validators | Record<string, Function> | - | 自定义验证器 | | theme | 'light' | 'dark' | 'light' | 主题 | | className | string | - | 自定义类名 | | style | CSSProperties | - | 自定义样式 | | showToolbar | boolean | true | 是否显示节点工具栏 | | toolbarPosition | 'top' | 'left' | 'right' | 'top' | 工具栏位置 | | availableNodeTypes | NodeTypeDefinition[] | 默认节点类型 | 可添加的节点类型 |

Events

| 事件名 | 参数 | 说明 | |--------|------|------| | onChange | (config: FlowConfig) | 配置变化时触发 | | onNodeClick | (node: NodeConfig) | 节点单击时触发 | | onNodeDoubleClick | (node: NodeConfig) | 节点双击时触发 | | onNodeAdd | (parentId: string, type: string) | 添加节点时触发 | | onNodeDelete | (nodeId: string) | 删除节点时触发 | | onEdgeAdd | (source: string, target: string) | 添加连线时触发 | | onEdgeDelete | (edgeId: string) | 删除连线时触发 |

示例

<FlowDesigner
  config={flowConfig}
  onChange={setFlowConfig}
  theme="light"
  showToolbar={true}
  toolbarPosition="top"
  onNodeDoubleClick={(node) => {
    console.log('配置节点:', node);
  }}
  onNodeAdd={(nodeId, type) => {
    console.log('添加节点:', nodeId, type);
  }}
/>

useFlowDesigner Hook

流程设计器状态管理 hook。

参数

interface UseFlowDesignerOptions {
  config: FlowConfig;              // 流程配置
  onChange?: (config: FlowConfig) => void;  // 配置变化回调
  enableHistory?: boolean;         // 是否启用历史记录
}

返回值

interface UseFlowDesignerReturn {
  config: FlowConfig;              // 当前流程配置
  flowModel: FlowModel;            // 流程模型实例
  nodes: NodeConfig[];             // 所有节点
  edges: EdgeConfig[];             // 所有连线
  addNode: (node: NodeConfig) => void;
  updateNode: (nodeId: string, updates: Partial<NodeConfig>) => void;
  removeNode: (nodeId: string) => void;
  getNode: (nodeId: string) => NodeConfig | undefined;
  addEdge: (edge: EdgeConfig) => void;
  updateEdge: (edgeId: string, updates: Partial<EdgeConfig>) => void;
  removeEdge: (edgeId: string) => void;
  getEdge: (edgeId: string) => EdgeConfig | undefined;
  validate: () => { valid: boolean; errors: string[]; warnings?: string[] };
}

类型定义

interface FlowConfig {
  id: string;
  name: string;
  version: string;
  nodes: NodeConfig[];
  edges: EdgeConfig[];
  settings: FlowSettings;
}

interface NodeConfig {
  id: string;
  type: string;
  title: string;
  config: Record<string, any>;
}

interface EdgeConfig {
  id: string;
  source: string;
  target: string;
  label?: string;
}

interface NodeTypeDefinition {
  type: string;
  label: string;
  icon: string;
  color: string;
  description?: string;
}

完整示例

请假审批流程

import React, { useState } from 'react';
import { FlowDesigner } from '@xiaoxiao6.0/flow-designer-react';
import type { FlowConfig, NodeConfig } from '@xiaoxiao6.0/flow-designer-react';

function LeaveApprovalFlow() {
  const [flowConfig, setFlowConfig] = useState<FlowConfig>({
    id: 'leave-approval',
    name: '请假审批流程',
    version: '1.0.0',
    nodes: [
      {
        id: 'start',
        type: 'start',
        title: '发起请假',
        config: {}
      },
      {
        id: 'approval-manager',
        type: 'approval',
        title: '直属主管审批',
        config: {
          approvers: ['manager']
        }
      },
      {
        id: 'approval-hr',
        type: 'approval',
        title: 'HR审批',
        config: {
          approvers: ['hr']
        }
      },
      {
        id: 'end',
        type: 'end',
        title: '结束',
        config: {}
      }
    ],
    edges: [
      { id: 'e1', source: 'start', target: 'approval-manager' },
      { id: 'e2', source: 'approval-manager', target: 'approval-hr' },
      { id: 'e3', source: 'approval-hr', target: 'end' }
    ],
    settings: {}
  });

  const handleFlowChange = (newConfig: FlowConfig) => {
    setFlowConfig(newConfig);
    console.log('流程配置已更新');
  };

  const handleNodeConfig = (node: NodeConfig) => {
    console.log('配置节点:', node);
    // 这里可以打开节点配置弹窗
  };

  const handleSave = async () => {
    try {
      // 保存到后端 API
      await fetch('/api/flows/leave-approval', {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(flowConfig)
      });
      alert('保存成功');
    } catch (error) {
      console.error('保存失败:', error);
    }
  };

  return (
    <div style={{ padding: '20px' }}>
      <h1>请假审批流程设计器</h1>

      <FlowDesigner
        config={flowConfig}
        onChange={handleFlowChange}
        onNodeDoubleClick={handleNodeConfig}
        showToolbar={true}
        toolbarPosition="top"
      />

      <div style={{ marginTop: '20px' }}>
        <button onClick={handleSave}>保存流程</button>
      </div>
    </div>
  );
}

export default LeaveApprovalFlow;

动态加载数据

import { FlowDesigner } from '@xiaoxiao6.0/flow-designer-react';

function App() {
  const [config, setConfig] = useState<FlowConfig | null>(null);

  useEffect(() => {
    // 从 API 加载流程配置
    fetch('/api/flows/my-flow')
      .then(res => res.json())
      .then(setConfig);
  }, []);

  if (!config) return <div>加载中...</div>;

  return (
    <FlowDesigner
      config={config}
      onChange={setConfig}
      loaders={{
        // 动态加载审批人列表
        options: async (field) => {
          if (field.name === 'approvers') {
            const res = await fetch('/api/users');
            const users = await res.json();
            return users.map(u => ({
              label: u.name,
              value: u.id
            }));
          }
          return field.options || [];
        }
      }}
    />
  );
}

自定义节点

你可以创建自定义节点组件：

import { Handle, Position } from 'reactflow';

interface CustomNodeProps {
  data: {
    title: string;
    description?: string;
  };
}

function CustomNode({ data }: CustomNodeProps) {
  return (
    <div style={{
      padding: '16px',
      border: '2px solid #1890ff',
      borderRadius: '8px',
      background: 'white'
    }}>
      <Handle type="target" position={Position.Top} />
      <div>
        <h3>{data.title}</h3>
        {data.description && <p>{data.description}</p>}
      </div>
      <Handle type="source" position={Position.Bottom} />
    </div>
  );
}

// 使用自定义节点
<FlowDesigner
  config={config}
  onChange={setConfig}
  nodeComponents={{
    custom: CustomNode
  }}
/>

样式定制

import 'reactflow/dist/style.css';

<FlowDesigner
  config={config}
  onChange={setConfig}
  theme="light"
  style={{
    width: '100%',
    height: '800px',
    border: '1px solid #e8e8e8',
    borderRadius: '8px'
  }}
  className="my-flow-designer"
/>

注意事项

必须导入 ReactFlow 样式：
```
import 'reactflow/dist/style.css';
```
React 版本要求：需要 React 18.0.0 或更高版本
受控组件：FlowDesigner 是完全受控的组件，需要通过 config 和 onChange 管理状态
节点工具栏：默认显示，可通过 showToolbar={false} 隐藏

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@xiaoxiao6.0/flow-designer-react

安装

特性

快速开始

基础使用

使用 Hook

API 文档

FlowDesigner 组件

Props

Events

示例

useFlowDesigner Hook

参数

返回值

类型定义

完整示例

请假审批流程

动态加载数据

自定义节点

样式定制

注意事项

相关链接

License