@blueking/bkflow-canvas-editor 0.0.1

package/README.md

@@ -0,0 +1,453 @@
+# bkflow-canvas-editor
+
+bkflow流程编辑组件，支持流程的编辑、查看以及创建并执行任务。
+
+## 安装
+
+```bash
+npm install bkflow-canvas-editor
+```
+
+## 使用
+
+### 基础使用
+
+```vue
+<template>
+  <FlowView
+    :flow-id="flowId"
+    :api-config="apiConfig"
+    :permissions="{ canEdit: true }"
+    @edit="handleEdit"
+    @back="handleBack" />
+</template>
+
+<script setup>
+  import { FlowView } from 'bkflow-canvas-editor';
+  import 'bkflow-canvas-editor/style';
+  import axios from 'axios';
+
+  const flowId = '123';
+
+  // 配置 API
+  const apiConfig = {
+    baseURL: window.API_HOST, // API 基础路径（可选，默认使用 window.API_HOST）
+    scopeData: {
+      scope_type: 'space',
+      scope_value: 123,
+    }, // 作用域数据（必需）
+    fetchUserApi: `${window.BK_COMPONENT_API_URL}/api/c/compapi/v2/usermanage/fs_list_users/`, // 用户查询 API（可选）
+    // 可选：使用自定义 axios 实例
+    // axiosInstance: customAxiosInstance,
+    // 可选：axios 配置
+    // axiosConfig: {
+    //   timeout: 10000,
+    //   headers: { ... }
+    // },
+  };
+
+  const handleEdit = () => {
+    // 跳转到编辑页面
+  };
+
+  const handleBack = () => {
+    // 返回处理
+  };
+</script>
+```
+
+## 组件 API
+
+### FlowView 组件
+
+流程查看组件，用于查看流程的详细信息。
+
+#### Props
+
+| 参数          | 类型                                       | 默认值                             | 说明                                                                                                                         |
+| ------------- | ------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `flowId`      | `string`                                   | -                                  | **必需**，流程 ID                                                                                                            |
+| `apiConfig`   | `FlowApiConfig`                            | -                                  | **必需**，API 配置对象，详见 [API 配置](#api-配置)                                                                           |
+| `permissions` | `{ canEdit?: boolean, canSave?: boolean }` | `{ canEdit: true, canSave: true }` | 权限配置对象，`canEdit`用来控制流程查看态时头部编辑按钮是否使用禁用样式，`canSave`用来控制流程编辑态时头部保存按钮是否可点击 |
+| `onEdit`      | `() => void`                               | -                                  | 编辑按钮点击回调（可选，也可以通过 `@edit` 事件监听）                                                                        |
+| `onBack`      | `() => void`                               | -                                  | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听）                                                                        |
+
+#### Slots
+
+| 插槽名        | 作用域参数 | 说明                   |
+| ------------- | ---------- | ---------------------- |
+| `header`      | -          | 自定义头部内容         |
+| `inputParams` | 见下方说明 | 自定义节点输入参数组件 |
+
+##### inputParams 插槽作用域参数
+
+| 参数                     | 类型                                                  | 说明                                                   |
+| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------ |
+| `node`                   | `Activity`                                            | 当前节点数据                                           |
+| `uniformApiPluginDetail` | `UniformApiPluginDetail \| null`                      | 统一 API 插件详情（仅 uniform_api 类型节点）           |
+| `inputs`                 | `UniformApiPluginInputsItem[]`                        | 输入参数表单配置列表                                   |
+| `editable`               | `boolean`                                             | 是否可编辑                                             |
+| `fullVariableList`       | `{ key: string; name: string }[]`                     | 完整变量列表（系统变量 + 常量）                        |
+| `updateInputParams`      | `(data: Record<string, PluginInputDataItem>) => void` | 更新节点输入参数的方法（暂存，需点击确定按钮才会保存） |
+
+#### Events
+
+| 事件名 | 参数 | 说明               |
+| ------ | ---- | ------------------ |
+| `edit` | -    | 点击编辑按钮时触发 |
+| `back` | -    | 点击返回按钮时触发 |
+
+---
+
+### FlowEdit 组件
+
+流程编辑组件，用于编辑流程的配置和节点信息。
+
+#### Props
+
+| 参数                 | 类型                                      | 默认值                  | 说明                                                     |
+| -------------------- | ----------------------------------------- | ----------------------- | -------------------------------------------------------- |
+| `flowId`             | `string`                                  | -                       | **必需**，流程 ID                                        |
+| `apiConfig`          | `FlowApiConfig`                           | -                       | **必需**，API 配置对象，详见 [API 配置](#api-配置)       |
+| `permissions`        | `{ canEdit?: boolean }`                   | `{}`                    | 权限配置对象                                             |
+| `pluginGroupIconMap` | `Record<string, string>`                  | `PLUGIN_GROUP_ICON_MAP` | 插件分组图标映射                                         |
+| `onSave`             | `(flowData: FlowTemplate) => void`        | -                       | 保存回调（可选，也可以通过 `@save` 事件监听）            |
+| `onSaveSuccess`      | `() => void`                              | -                       | 保存成功回调（可选，也可以通过 `@saveSuccess` 事件监听） |
+| `onBack`             | `() => void`                              | -                       | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听）    |
+| `onBeforeLeave`      | `(isEdited: boolean) => Promise<boolean>` | -                       | 离开前回调，返回 `false` 可阻止离开                      |
+
+#### Slots
+
+| 插槽名        | 作用域参数 | 说明                   |
+| ------------- | ---------- | ---------------------- |
+| `header`      | -          | 自定义头部内容         |
+| `inputParams` | 见下方说明 | 自定义节点输入参数组件 |
+
+##### inputParams 插槽作用域参数
+
+| 参数                     | 类型                                                         | 说明                                                                                     |
+| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `node`                   | `Activity`                                                   | 当前节点数据                                                                             |
+| `uniformApiPluginDetail` | `UniformApiPluginDetail \| null`                             | 统一 API 插件详情（仅 uniform_api 类型节点）                                             |
+| `inputs`                 | `UniformApiPluginInputsItem[]`                               | 输入参数表单配置列表                                                                     |
+| `editable`               | `boolean`                                                    | 是否可编辑                                                                               |
+| `fullVariableList`       | `{ key: string; name: string }[]`                            | 完整变量列表（系统变量 + 常量）                                                          |
+| `updateInputParams`      | `(data: Record<string, PluginInputDataItem>) => void`        | 更新节点输入参数的方法（暂存到节点配置面板，需点击确定按钮才会保存）                     |
+| `updateNodeInputParams`  | `(inputParams: Record<string, PluginInputDataItem>) => void` | 更新节点输入参数的方法（通过 edit 组件调用，暂存到节点配置面板，需点击确定按钮才会保存） |
+
+#### Events
+
+| 事件名        | 参数                     | 说明                       |
+| ------------- | ------------------------ | -------------------------- |
+| `save`        | `flowData: FlowTemplate` | 保存时触发，参数为流程数据 |
+| `saveSuccess` | -                        | 保存成功时触发             |
+| `back`        | -                        | 点击返回按钮时触发         |
+
+#### 暴露的方法
+
+通过 `ref` 可以访问组件实例：
+
+| 方法名                  | 参数                                               | 返回值                 | 说明                                                       |
+| ----------------------- | -------------------------------------------------- | ---------------------- | ---------------------------------------------------------- |
+| `updateNodeInputParams` | `inputParams: Record<string, PluginInputDataItem>` | `void`                 | 更新当前打开节点的输入参数（暂存，需点击确定按钮才会保存） |
+| `isFlowEdited`          | -                                                  | `ComputedRef<boolean>` | 流程是否已编辑（只读）                                     |
+
+---
+
+### FlowExecute 组件
+
+流程执行组件，用于执行流程任务。
+
+#### Props
+
+| 参数               | 类型                                           | 默认值  | 说明                                                                                       |
+| ------------------ | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `flowId`           | `string`                                       | -       | **必需**，流程 ID                                                                          |
+| `show`             | `boolean`                                      | -       | **必需**，是否显示执行面板                                                                 |
+| `apiConfig`        | `FlowApiConfig`                                | -       | **必需**，API 配置对象，详见 [API 配置](#api-配置)。注意：需要通过 `useFlowApi` 转换后传入 |
+| `editable`         | `boolean`                                      | `true`  | 是否可编辑                                                                                 |
+| `showFlowEntry`    | `boolean`                                      | `false` | 是否显示流程入口                                                                           |
+| `onExecuteSuccess` | `(taskId: string, templateId: string) => void` | -       | 执行成功回调                                                                               |
+
+#### Events
+
+| 事件名        | 参数                                 | 说明               |
+| ------------- | ------------------------------------ | ------------------ |
+| `confirm`     | `taskId: string, templateId: string` | 执行确认时触发     |
+| `close`       | -                                    | 关闭面板时触发     |
+| `update:show` | `show: boolean`                      | 显示状态更新时触发 |
+
+---
+
+## 使用示例
+
+### 基础使用
+
+```vue
+<template>
+  <FlowEdit
+    :flow-id="flowId"
+    :api-config="apiConfig"
+    :permissions="{ canEdit: true }"
+    @save="handleSave"
+    @save-success="handleSaveSuccess"
+    @back="handleBack" />
+</template>
+
+<script setup>
+  import { FlowEdit } from 'bkflow-canvas-editor';
+
+  const flowId = '123';
+  const apiConfig = {
+    baseURL: window.API_HOST,
+    scopeData: {
+      scope_type: 'space',
+      scope_value: 123,
+    },
+  };
+
+  const handleSave = (flowData) => {
+    console.log('保存流程:', flowData);
+  };
+
+  const handleSaveSuccess = () => {
+    console.log('保存成功');
+  };
+
+  const handleBack = () => {
+    // 返回处理
+  };
+</script>
+```
+
+### 使用自定义 InputParams 插槽
+
+当需要自定义节点输入参数的渲染时，可以使用 `inputParams` 插槽：
+
+```vue
+<template>
+  <FlowEdit
+    ref="flowEditRef"
+    :flow-id="flowId"
+    :api-config="apiConfig"
+    :permissions="{ canEdit: true }"
+    @save="handleSave">
+    <!-- 自定义输入参数组件 -->
+    <template
+      #inputParams="{
+        node,
+        uniformApiPluginDetail,
+        inputs,
+        editable,
+        fullVariableList,
+        updateInputParams,
+        updateNodeInputParams,
+      }">
+      <CustomInputParams
+        :node="node"
+        :plugin-detail="uniformApiPluginDetail"
+        :inputs="inputs"
+        :editable="editable"
+        :full-variable-list="fullVariableList"
+        @change="handleInputParamsChange($event, updateInputParams)" />
+    </template>
+  </FlowEdit>
+</template>
+
+<script setup>
+  import { ref } from 'vue';
+  import { FlowEdit, type PluginInputDataItem } from "bkflow-canvas-editor";
+  import CustomInputParams from "./components/CustomInputParams.vue";
+
+  const flowEditRef = ref();
+  const flowId = "123";
+  const apiConfig = {
+    baseURL: window.API_HOST,
+    scopeData: {
+      scope_type: "space",
+      scope_value: 123,
+    },
+  };
+
+  // 处理输入参数变化
+  const handleInputParamsChange = (
+    data: Record<string, PluginInputDataItem>,
+    updateInputParams: (data: Record<string, PluginInputDataItem>) => void
+  ) => {
+    // 方式1：使用插槽提供的 updateInputParams 方法（推荐）
+    // 这会暂存数据到节点配置面板，用户点击"确定"按钮后才会真正保存
+    updateInputParams(data);
+
+    // 方式2：通过 ref 调用组件方法（适用于需要在外部更新）
+    // flowEditRef.value?.updateNodeInputParams(data);
+  };
+</script>
+```
+
+### 使用自定义 axios 实例
+
+如果需要使用已配置好的 axios 实例（包含拦截器等），可以传入 `axiosInstance`：
+
+```vue
+<script setup>
+  import { FlowView } from 'bkflow-canvas-editor';
+  import http from '@/api'; // 你的 axios 实例
+
+  const apiConfig = {
+    axiosInstance: http, // 使用自定义 axios 实例
+    scopeData: {
+      scope_type: 'space',
+      scope_value: 123,
+    },
+  };
+</script>
+```
+
+### 监听流程编辑状态
+
+```vue
+<template>
+  <FlowEdit ref="flowEditRef" :flow-id="flowId" :api-config="apiConfig" @back="handleBack" />
+</template>
+
+<script setup>
+  import { ref, watch } from 'vue';
+  import { FlowEdit } from 'bkflow-canvas-editor';
+
+  const flowEditRef = ref();
+
+  // 监听流程编辑状态
+  watch(
+    () => flowEditRef.value?.isFlowEdited,
+    (isEdited) => {
+      if (isEdited) {
+        console.log('流程已被编辑');
+      }
+    },
+  );
+</script>
+```
+
+### 使用自定义头部
+
+```vue
+<template>
+  <FlowEdit :flow-id="flowId" :api-config="apiConfig">
+    <template #header>
+      <div class="custom-header">
+        <h2>自定义头部</h2>
+      </div>
+    </template>
+  </FlowEdit>
+</template>
+```
+
+## API 配置
+
+### FlowApiConfig
+
+组件需要的 API 配置接口：
+
+```typescript
+interface FlowApiConfig {
+  /** API 基础路径（可选，默认使用 window.API_HOST） */
+  baseURL?: string;
+  /** 自定义 axios 实例（可选，如果提供则优先使用） */
+  axiosInstance?: AxiosInstance;
+  /** axios 配置（可选，用于创建新的 axios 实例） */
+  axiosConfig?: AxiosRequestConfig;
+  /** 作用域数据（必需，由外部传入） */
+  scopeData: {
+    scope_type: string;
+    scope_value: number;
+  };
+  /** 用户查询 API 地址（可选） */
+  fetchUserApi?: string;
+}
+```
+
+组件内部会自动实现所有 API 方法，包括：
+
+- `fetchFlowDetail` - 获取流程详情
+- `fetchSpaceFlowConfig` - 获取空间配置
+- `fetchSystemVariables` - 获取系统变量
+- `saveFlow` - 保存流程（仅 FlowEdit）
+- `fetchPluginCategoryList` - 获取插件分类列表（仅 FlowEdit）
+- `fetchCategoryPlugins` - 获取分类插件（仅 FlowEdit）
+- `fetchPluginDetail` - 获取插件详情（可选）
+- `fetchApplyInstructionData` - 获取指令数据（可选）
+- `fetchVariableRef` - 获取变量引用（可选）
+- `fetchCustomVariableTypes` - 获取自定义变量类型（可选）
+- `fetchFlowOperateRecord` - 获取操作记录（可选）
+- `createFlowTask` - 创建流程任务（可选）
+- `executeFlowTask` - 执行流程任务（可选）
+
+所有 API 请求会自动合并 `scopeData` 到请求参数中。
+
+## 类型定义
+
+所有类型定义都可以从包中导入：
+
+```typescript
+import type {
+  FlowTemplate,
+  SpaceFlowConfig,
+  PluginGroupConfig,
+  GroupPluginItem,
+  UpdateFlowParams,
+  FlowApiConfig,
+  Variable,
+  PipelineTree,
+  Activity,
+  PluginInputDataItem,
+  UniformApiPluginInputsItem,
+  UniformApiPluginDetail,
+  // ... 更多类型
+} from 'bkflow-canvas-editor';
+```
+
+> **注意**：`FlowViewApiConfig` 和 `FlowEditApiConfig` 是组件内部使用的类型，外部使用者只需要使用 `FlowApiConfig`。组件内部会通过 `useFlowApi` 自动将 `FlowApiConfig` 转换为所需的 API 方法接口。
+
+## 本地开发
+
+如果需要在当前项目中使用本地开发版本，可以在 `frontend/package.json` 中添加：
+
+```json
+{
+  "dependencies": {
+    "bkflow-canvas-editor": "file:../bkflow-canvas-editor"
+  }
+}
+```
+
+然后在 `frontend/vite.config.ts` 中添加别名：
+
+```typescript
+resolve: {
+  alias: {
+    'bkflow-canvas-editor': resolve(__dirname, '../bkflow-canvas-editor/src'),
+  },
+}
+```
+
+## 注意事项
+
+1. **scopeData 必需**：`scopeData` 是必需的配置项，必须由外部传入，组件内部不会处理或设置默认值
+2. **API 自动处理**：所有 API 调用由组件内部自动处理，无需手动实现 API 方法
+3. **axios 实例优先级**：如果提供了 `axiosInstance`，组件会优先使用该实例；否则会根据 `baseURL` 和 `axiosConfig` 创建新的 axios 实例
+4. **自动合并 scopeData**：所有 API 请求会自动合并 `scopeData` 到请求参数中（GET 请求合并到 params，POST/PUT 请求合并到请求体）
+5. **权限检查**：权限检查通过 `permissions` props 传入布尔值
+6. **路由跳转**：路由跳转需要通过事件回调处理，组件内部不直接使用 vue-router
+7. **样式引入**：样式文件需要单独引入：`import 'bkflow-canvas-editor/style'`
+8. **输入参数更新机制**：
+   - 使用 `inputParams` 插槽时，通过 `updateInputParams` 或 `updateNodeInputParams` 方法更新的数据会暂存到节点配置面板
+   - 用户需要点击节点配置面板的"确定"按钮，数据才会真正保存到流程中
+   - 这种设计允许用户在保存前多次修改和预览
+9. **API 配置类型说明**：
+   - 外部使用者只需要使用 `FlowApiConfig` 类型
+   - `FlowViewApiConfig` 和 `FlowEditApiConfig` 是组件内部使用的类型，通过 `useFlowApi` 自动转换
+   - 如果直接使用 `FlowExecute` 组件，需要通过 `useFlowApi` 将 `FlowApiConfig` 转换后传入
+
+## License
+
+MIT