@blueking/bkflow-canvas-editor-vue2

Vue 2.7 适配层，通过 Vue 3 Island 模式在 Vue 2 项目中使用 @blueking/bkflow-canvas-editor。

Vue 3 运行时、bkflow-canvas-editor 及其所有 Vue 3 生态依赖已内置打包，宿主项目无需单独安装。

安装

npm install @blueking/bkflow-canvas-editor-vue2

仅此一步。适配包已内置以下依赖，宿主项目无需额外安装：

• Vue 3 运行时
• @blueking/bkflow-canvas-editor + @blueking/flow-canvas
• bkui-vue、element-plus、pinia
• @antv/x6 及所有 X6 插件
• sortablejs、xlsx 等

共享依赖（peerDependencies）

以下库不内置，由宿主项目提供（大概率已安装）：

| 依赖 | 版本 | 说明 | | ------------- | -------- | ------------------------------------ | | vue | ^2.7.0 | 宿主 Vue 版本 | | axios | ^1.6.0 | HTTP 请求 | | lodash | ^4.17.21 | 工具库 | | monaco-editor | ^0.45.0 | 代码编辑器（可选，仅 FlowEdit 需要） |

如果宿主项目缺少某个共享依赖，按需安装即可：

npm install axios lodash monaco-editor

无需 Webpack 配置

Vue 3 运行时已打包进适配层内部，不需要：

• ~~npm install vue3@npm:vue@^3.5.0~~（Vue 3 别名安装）
• ~~NormalModuleReplacementPlugin~~（Webpack 插件配置）
• ~~安装 bkflow-canvas-editor 的 15+ 个 peer 依赖~~

使用方式

引入样式

import '@blueking/bkflow-canvas-editor-vue2/style';

按需引入（推荐）

每个组件支持独立导入，宿主的打包工具只会加载实际用到的组件及其依赖的公共 chunk：

import { FlowViewBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-view';
import { FlowEditBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-edit';
import { FlowCreateTaskBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-create-task';
import { FlowExecuteBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-execute';
import { FlowDebugBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-debug';

也可以从主入口全量引入（向后兼容）：

import { FlowEditBridge, FlowViewBridge } from '@blueking/bkflow-canvas-editor-vue2';

FlowEditBridge（流程编辑）

<template>
  <FlowEditBridge
    :flow-id="flowId"
    :api-config="apiConfig"
    :permissions="{ canSave: true }"
    :enable-debug="true"
    :on-before-leave="handleBeforeLeave"
    @save="handleSave"
    @back="handleBack" />
</template>

<script>
  import { FlowEditBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-edit';

  export default {
    components: { FlowEditBridge },
    data() {
      return {
        flowId: 'xxx',
        apiConfig: {
          baseURL: '/api/bkflow',
          scopeData: { scope_type: 'project', scope_value: 1 },
        },
      };
    },
    methods: {
      handleSave(flowData) {
        console.log('保存', flowData);
      },
      handleBack() {
        this.$router.back();
      },
      handleBeforeLeave(isEdited) {
        if (!isEdited) return Promise.resolve(true);
        return new Promise((resolve) => {
          this.$bkInfo({
            title: '确认离开？',
            confirmFn: () => resolve(true),
            cancelFn: () => resolve(false),
          });
        });
      },
    },
  };
</script>

FlowViewBridge（流程查看）

<template>
  <FlowViewBridge :flow-id="flowId" :api-config="apiConfig" :thumbnail="false" @edit="goEdit" @back="goBack" />
</template>

<script>
  import { FlowViewBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-view';

  export default {
    components: { FlowViewBridge },
  };
</script>

FlowCreateTaskBridge（创建任务）

支持 .sync 修饰符控制显示/隐藏：

<template>
  <FlowCreateTaskBridge
    :flow-id="flowId"
    :show.sync="showDialog"
    :api-config="apiConfig"
    @confirm="handleConfirm"
    @close="showDialog = false" />
</template>

<script>
  import { FlowCreateTaskBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-create-task';

  export default {
    components: { FlowCreateTaskBridge },
    data() {
      return { showDialog: false };
    },
  };
</script>

FlowExecuteBridge（流程执行态查看）

<template>
  <FlowExecuteBridge
    :pipeline-tree="pipelineTree"
    :node-states="nodeStates"
    :api-config="apiConfig"
    :default-zoom="0.8"
    @back="goBack"
    @node-click="handleNodeClick" />
</template>

<script>
  import { FlowExecuteBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-execute';

  export default {
    components: { FlowExecuteBridge },
  };
</script>

FlowDebugBridge（流程调试）

<template>
  <FlowDebugBridge
    :flow-id="flowId"
    :show.sync="showDebug"
    :api-config="apiConfig"
    @confirm="handleDebugConfirm"
    @close="showDebug = false" />
</template>

<script>
  import { FlowDebugBridge } from '@blueking/bkflow-canvas-editor-vue2/flow-debug';

  export default {
    components: { FlowDebugBridge },
    data() {
      return { showDebug: false };
    },
  };
</script>

工作原理

Vue 2.7 宿主应用
  └─ FlowEditBridge (Vue 2.7 defineComponent)
       ├─ <div class="bkflow-vue3-island" />   ← 容器
       └─ onMounted → Vue3.createApp(FlowEdit).mount(容器)

每个桥接组件内部创建一个独立的 Vue 3 应用实例（Vue 3 运行时已打包在内）：

• Vue 2.7 侧声明 props/emits，与宿主应用交互
• Vue 3 侧通过 reactive() 持有 props 副本，由 watch 单向同步
• 事件从 Vue 3 → Vue 2 通过回调函数桥接
• 两套 Vue 运行时完全隔离，互不干扰

产物结构

构建采用多入口 + 公共 chunk 拆分策略，宿主按需引入时只加载必要的代码：

dist/
├── index.esm.js / index.cjs.js                # 主入口（re-export 所有组件）
├── flow-edit.esm.js / flow-edit.cjs.js         # FlowEditBridge 入口
├── flow-view.esm.js / flow-view.cjs.js         # FlowViewBridge 入口
├── flow-create-task.esm.js / ...               # FlowCreateTaskBridge 入口
├── flow-execute.esm.js / ...                   # FlowExecuteBridge 入口
├── flow-debug.esm.js / ...                     # FlowDebugBridge 入口
├── vendor-vue3-[hash].js                       # 公共 chunk: Vue 3 运行时
├── vendor-x6-[hash].js                         # 公共 chunk: AntV X6 画布引擎
├── vendor-[hash].js                            # 公共 chunk: bkui-vue、pinia 等
├── bkflow-core-[hash].js                       # 公共 chunk: bkflow-canvas-editor 核心
├── bkflow-canvas-editor-vue2.css               # 全部样式
└── stats.html                                  # 体积分析报告

API 参考

FlowEditBridge

| Props | 类型 | 必需 | 默认值 | 说明 | | --------------------- | ----------------------------------------- | ---- | ----------------- | --------------------------------- | | flowId | string | 是 | - | 流程 ID | | apiConfig | FlowApiConfig | 是 | - | API 配置（baseURL、scopeData 等） | | permissions | { canSave?: boolean } | 否 | { canSave: true } | 权限配置 | | enableDebug | boolean | 否 | false | 启用调试模式 | | onDebugConfirm | Function | 否 | - | 调试确认回调（支持返回 Promise） | | useCustomDebugConfirm | boolean | 否 | false | 使用自定义调试确认逻辑 | | selectPanelConfig | object | 否 | - | 选择面板配置 | | onBeforeLeave | (isEdited: boolean) => Promise<boolean> | 否 | - | 离开前确认回调 | | enableVersion | boolean | 否 | false | 启用版本管理 | | flowVersion | string | 否 | - | 流程版本号 | | defaultZoom | number | 否 | 1 | 默认缩放比例 | | bkflowSaasUrl | string | 否 | - | BKFlow SaaS 地址 | | enableThirdPlugin | boolean | 否 | true | 启用第三方插件 | | quickAdd | object | 否 | - | 快速添加节点配置 |

| Events | 参数 | 说明 | | ------------------ | ---------------------- | -------------- | | save | flowData: FlowTemplate | 保存流程 | | save-success | - | 保存成功 | | back | - | 返回 | | exit-edit | - | 退出编辑 | | debug-before-close | - | 调试面板关闭前 |

| Expose | 类型 | 说明 | | --------------------- | ---------------- | ---------------- | | isFlowEdited | boolean (getter) | 流程是否已编辑 | | updateNodeInputParams | Function | 更新节点输入参数 | | openGlobalVariables | Function | 打开全局变量面板 |

FlowViewBridge

| Props | 类型 | 必需 | 默认值 | 说明 | | ----------------- | --------------------- | ---- | ----------------- | -------------------------------- | | flowId | string | 是 | - | 流程 ID | | apiConfig | FlowApiConfig | 是 | - | API 配置 | | permissions | { canEdit?: boolean } | 否 | { canEdit: true } | 权限配置 | | onEdit | Function | 否 | - | 点击编辑回调（优先于 edit 事件） | | onBack | Function | 否 | - | 点击返回回调（优先于 back 事件） | | thumbnail | boolean | 否 | false | 缩略图模式 | | enableVersion | boolean | 否 | false | 启用版本管理 | | flowVersion | string | 否 | - | 流程版本号 | | showHeaderActions | boolean | 否 | true | 显示顶部操作按钮 | | defaultZoom | number | 否 | 1 | 默认缩放比例 | | bkflowSaasUrl | string | 否 | - | BKFlow SaaS 地址 | | onExecuteSuccess | Function | 否 | - | 执行成功回调 |

| Events | 说明 | | ------ | ----------------------------------- | | edit | 点击编辑（未传 onEdit prop 时触发） | | back | 点击返回（未传 onBack prop 时触发） |

FlowCreateTaskBridge

| Props | 类型 | 必需 | 默认值 | 说明 | | ---------------- | ------------- | ---- | ------ | ----------------------------- | | flowId | string | 是 | - | 流程 ID | | show | boolean | 是 | - | 控制显示/隐藏（支持 .sync） | | apiConfig | FlowApiConfig | 是 | - | API 配置 | | editable | boolean | 否 | true | 是否可编辑 | | showFlowEntry | boolean | 否 | false | 显示流程入口 | | onExecuteSuccess | Function | 否 | - | 执行成功回调 | | bkflowSaasUrl | string | 否 | - | BKFlow SaaS 地址 |

| Events | 说明 | | ------------ | ---------------------------- | | confirm | 确认创建任务 | | close | 关闭面板 | | update:show | 显示状态变更（支持 .sync） | | before-close | 关闭前触发 | | view-flow | 查看排障流程 |

FlowExecuteBridge

| Props | 类型 | 必需 | 默认值 | 说明 | | ------------- | ------------- | ---- | ------ | ------------------------------ | | pipelineTree | object | 是 | - | 流程执行态的 PipelineTree 数据 | | nodeStates | object | 否 | {} | 节点执行状态 | | defaultZoom | number | 否 | 1 | 默认缩放比例 | | apiConfig | FlowApiConfig | 是 | - | API 配置 | | bkflowSaasUrl | string | 否 | - | BKFlow SaaS 地址 | | onBack | Function | 否 | - | 返回回调（优先于 back 事件） |

| Events | 参数 | 说明 | | ---------- | ----- | ----------------------------------- | | back | - | 点击返回（未传 onBack prop 时触发） | | node-click | event | 点击节点 | | ui-event | event | UI 交互事件 |

FlowDebugBridge

| Props | 类型 | 必需 | 默认值 | 说明 | | ---------------- | ------------- | ---- | ------ | ------------------------------- | | flowId | string | 是 | - | 流程 ID | | show | boolean | 是 | - | 控制显示/隐藏（支持 .sync） | | apiConfig | FlowApiConfig | 是 | - | API 配置 | | editable | boolean | 否 | true | 是否可编辑 | | showFlowEntry | boolean | 否 | false | 显示流程入口 | | onConfirm | Function | 否 | - | 确认回调（优先于 confirm 事件） | | useCustomConfirm | boolean | 否 | false | 使用自定义确认逻辑 | | onExecuteSuccess | Function | 否 | - | 执行成功回调 | | bkflowSaasUrl | string | 否 | - | BKFlow SaaS 地址 | | enableVersion | boolean | 否 | false | 启用版本管理 | | flowVersion | string | 否 | - | 流程版本号 |

| Events | 说明 | | ------------ | -------------------------------------- | | confirm | 确认调试（未传 onConfirm prop 时触发） | | close | 关闭面板 | | update:show | 显示状态变更（支持 .sync） | | before-close | 关闭前触发 |

FlowApiConfig

所有组件的 apiConfig prop 类型定义：

interface FlowApiConfig {
  baseURL?: string; // API 基础路径
  axiosInstance?: AxiosInstance; // 自定义 axios 实例（优先使用）
  axiosConfig?: AxiosRequestConfig; // axios 配置（用于创建新实例）
  xsrfCookieName?: string; // CSRF cookie 名称
  scopeData: {
    // 作用域数据（必填）
    scope_type: string;
    scope_value: number;
  };
  fetchUserApi?: string; // 用户查询 API 地址
  enableThirdPlugin?: boolean; // 启用第三方插件（默认 true）
}

自定义桥接

如需桥接其他 Vue 3 组件，可使用底层工具函数 createVue3Island：

import { createVue3Island } from '@blueking/bkflow-canvas-editor-vue2';

const SomeBridge = createVue3Island({
  name: 'SomeBridge',
  vue3Component: SomeVue3Component,
  props: {
    title: { type: String, required: true },
    data: { type: Object, default: () => ({}) },
  },
  emits: ['change', 'submit'],
  mapProps: (state, emit) => ({
    ...state,
    onChange: (...args) => emit('change', ...args),
    onSubmit: (...args) => emit('submit', ...args),
  }),
  // 可选：转发 Vue 3 组件的 expose
  expose: (getRef) => ({
    get someValue() {
      return getRef()?.someValue?.value;
    },
    someMethod(...args) {
      return getRef()?.someMethod?.(...args);
    },
  }),
});

BridgeConfig 配置说明：

| 字段 | 类型 | 说明 | | ------------- | ----------------------------- | ------------------------------------------ | | name | string | 组件名称 | | vue3Component | Component | Vue 3 组件 | | props | Record<string, PropOptions> | Vue 2 props 定义 | | emits | string[] | Vue 2 事件名列表 | | mapProps | (state, emit) => object | 将 props 状态和事件转换为 Vue 3 h() 的参数 | | expose | (getRef) => object | 转发 Vue 3 组件的 expose（可选） |

注意事项

• 容器尺寸：桥接组件的容器 div 设置了 width: 100%; height: 100%，请确保父元素提供了明确的高度
• Vue Devtools：Vue 3 Island 内部的组件需安装 Vue 3 版本的 Devtools 扩展才能调试
• 升级路径：当宿主项目升级到 Vue 3 后，可直接移除适配层，改用 @blueking/bkflow-canvas-editor 原生导入
• 体积分析：构建后查看 dist/stats.html 可视化报告，定位体积优化方向