@blueking/bkflow-canvas-editor 0.0.16 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +178 -8
  2. package/dist/index.cjs.js +11 -11
  3. package/dist/index.esm.js +1147 -1070
  4. package/dist/style.css +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -64,14 +64,19 @@ npm install bkflow-canvas-editor
64
64
 
65
65
  #### Props
66
66
 
67
- | 参数 | 类型 | 默认值 | 说明 |
68
- | ------------- | ------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
69
- | `flowId` | `string` | - | **必需**，流程 ID |
70
- | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
71
- | `permissions` | `{ canEdit?: boolean, canSave?: boolean }` | `{ canEdit: true, canSave: true }` | 权限配置对象，`canEdit`用来控制流程查看态时头部编辑按钮是否使用禁用样式，`canSave`用来控制流程编辑态时头部保存按钮是否可点击 |
72
- | `thumbnail` | `boolean` | `false` | 缩略图模式，启用后只显示画布内容，不显示顶部 header 和操作按钮，禁用节点点击事件 |
73
- | `onEdit` | `() => void` | - | 编辑按钮点击回调（可选，也可以通过 `@edit` 事件监听） |
74
- | `onBack` | `() => void` | - | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听） |
67
+ | 参数 | 类型 | 默认值 | 说明 |
68
+ | ----------------- | ------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
69
+ | `flowId` | `string` | - | **必需**，流程 ID |
70
+ | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
71
+ | `permissions` | `{ canEdit?: boolean, canSave?: boolean }` | `{ canEdit: true, canSave: true }` | 权限配置对象，`canEdit`用来控制流程查看态时头部编辑按钮是否使用禁用样式，`canSave`用来控制流程编辑态时头部保存按钮是否可点击 |
72
+ | `thumbnail` | `boolean` | `false` | 缩略图模式，启用后只显示画布内容，不显示顶部 header 和操作按钮，禁用节点点击事件 |
73
+ | `enableVersion` | `boolean` | `false` | 是否开启流程版本功能，开启后会根据 `flowVersion` 的值获取对应版本的流程数据 |
74
+ | `flowVersion` | `string` | - | 流程版本号，仅在 `enableVersion` 为 `true` 时生效。为空时表示草稿版本，不为空时表示指定版本 |
75
+ | `showHeaderActions` | `boolean` | `true` | 是否显示头部操作按钮（编辑、执行流程、调试），仅在非缩略图模式下生效 |
76
+ | `defaultZoom` | `number` | `1` | x6 画布的默认缩放比例，用于控制画布的初始显示效果。取值范围建议在 0.25 到 1.5 之间 |
77
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
78
+ | `onEdit` | `() => void` | - | 编辑按钮点击回调（可选，也可以通过 `@edit` 事件监听） |
79
+ | `onBack` | `() => void` | - | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听） |
75
80
 
76
81
  #### Slots
77
82
 
@@ -112,6 +117,8 @@ npm install bkflow-canvas-editor
112
117
  | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
113
118
  | `permissions` | `{ canEdit?: boolean }` | `{}` | 权限配置对象 |
114
119
  | `enableDebug` | `boolean` | `false` | 是否启用调试功能，启用后显示可点击的调试按钮 |
120
+ | `enableVersion` | `boolean` | `false` | 是否开启流程版本功能，开启后会根据 `flowVersion` 的值获取对应版本的流程数据 |
121
+ | `flowVersion` | `string` | - | 流程版本号，仅在 `enableVersion` 为 `true` 时生效。为空时表示草稿版本，不为空时表示指定版本 |
115
122
  | `onDebugConfirm` | `(formData: { name: string, variablesValue: Record<string, any> }) => Promise<void> \| void` | - | 调试面板确定按钮回调（可选） |
116
123
  | `useCustomDebugConfirm` | `boolean` | `false` | 是否使用自定义回调替代调试面板原有逻辑。为 `true` 时只执行 `onDebugConfirm`，为 `false` 时在原有逻辑后执行 `onDebugConfirm` |
117
124
  | `agentSelectPanelConfig` | `AgentSelectPanelConfig` | - | 智能体选择面板配置（可选），详见 [AgentSelectPanelConfig](#agentselectpanelconfig) |
@@ -119,6 +126,8 @@ npm install bkflow-canvas-editor
119
126
  | `onSaveSuccess` | `() => void` | - | 保存成功回调（可选，也可以通过 `@saveSuccess` 事件监听） |
120
127
  | `onBack` | `() => void` | - | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听） |
121
128
  | `onBeforeLeave` | `(isEdited: boolean) => Promise<boolean>` | - | 离开前回调，返回 `false` 可阻止离开 |
129
+ | `defaultZoom` | `number` | `1` | x6 画布的默认缩放比例，用于控制画布的初始显示效果。取值范围建议在 0.25 到 1.5 之间 |
130
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
122
131
 
123
132
  #### Slots
124
133
 
@@ -217,6 +226,7 @@ interface AgentSelectPanelConfig {
217
226
  | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
218
227
  | `editable` | `boolean` | `true` | 是否可编辑 |
219
228
  | `showFlowEntry` | `boolean` | `false` | 是否显示流程入口 |
229
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
220
230
  | `onExecuteSuccess` | `(taskId: string, templateId: string) => void` | - | 执行成功回调 |
221
231
 
222
232
  #### Events
@@ -242,6 +252,7 @@ interface AgentSelectPanelConfig {
242
252
  | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
243
253
  | `editable` | `boolean` | `true` | 是否可编辑 |
244
254
  | `showFlowEntry` | `boolean` | `false` | 是否显示流程入口 |
255
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
245
256
  | `onConfirm` | `(formData: { name: string, variablesValue: Record<string, any> }) => Promise<void> \| void` | - | 自定义确定按钮回调（可选） |
246
257
  | `useCustomConfirm` | `boolean` | `false` | 是否使用自定义回调替代原有逻辑。为 `true` 时只执行 `onConfirm`，为 `false` 时在原有逻辑后执行 `onConfirm` |
247
258
  | `onExecuteSuccess` | `(taskId: string, templateId: string) => void` | - | 执行成功回调（可选，仅在 `useCustomConfirm` 为 `false` 时生效） |
@@ -456,6 +467,152 @@ interface AgentSelectPanelConfig {
456
467
  </script>
457
468
  ```
458
469
 
470
+ ### 使用流程版本功能
471
+
472
+ 当需要查看或编辑特定版本的流程时，可以使用版本功能：
473
+
474
+ ```vue
475
+ <template>
476
+ <!-- 查看指定版本的流程 -->
477
+ <FlowView
478
+ :flow-id="flowId"
479
+ :api-config="apiConfig"
480
+ :enable-version="true"
481
+ :flow-version="'v1.0.0'" />
482
+
483
+ <!-- 查看草稿版本的流程 -->
484
+ <FlowView
485
+ :flow-id="flowId"
486
+ :api-config="apiConfig"
487
+ :enable-version="true" />
488
+
489
+ <!-- 编辑指定版本的流程 -->
490
+ <FlowEdit
491
+ :flow-id="flowId"
492
+ :api-config="apiConfig"
493
+ :enable-version="true"
494
+ :flow-version="'v1.0.0'" />
495
+ </template>
496
+
497
+ <script setup>
498
+ import { FlowView, FlowEdit } from 'bkflow-canvas-editor';
499
+
500
+ const flowId = '123';
501
+ const apiConfig = {
502
+ scopeData: {
503
+ scope_type: 'space',
504
+ scope_value: 123,
505
+ },
506
+ };
507
+ </script>
508
+ ```
509
+
510
+ ### 控制头部操作按钮显示
511
+
512
+ 在 `FlowView` 组件中，可以通过 `showHeaderActions` props 控制头部操作按钮（编辑、执行流程、调试）的显示：
513
+
514
+ ```vue
515
+ <template>
516
+ <!-- 隐藏头部操作按钮 -->
517
+ <FlowView
518
+ :flow-id="flowId"
519
+ :api-config="apiConfig"
520
+ :show-header-actions="false" />
521
+ </template>
522
+
523
+ <script setup>
524
+ import { FlowView } from 'bkflow-canvas-editor';
525
+
526
+ const flowId = '123';
527
+ const apiConfig = {
528
+ scopeData: {
529
+ scope_type: 'space',
530
+ scope_value: 123,
531
+ },
532
+ };
533
+ </script>
534
+ ```
535
+
536
+ ### 设置画布默认缩放比例
537
+
538
+ 可以通过 `defaultZoom` props 控制 x6 画布的初始缩放比例，用于调整画布的默认显示效果：
539
+
540
+ ```vue
541
+ <template>
542
+ <!-- 设置画布默认缩放为 80% -->
543
+ <FlowView
544
+ :flow-id="flowId"
545
+ :api-config="apiConfig"
546
+ :default-zoom="0.8" />
547
+
548
+ <!-- 设置画布默认缩放为 75% -->
549
+ <FlowEdit
550
+ :flow-id="flowId"
551
+ :api-config="apiConfig"
552
+ :default-zoom="0.75" />
553
+ </template>
554
+
555
+ <script setup>
556
+ import { FlowView, FlowEdit } from 'bkflow-canvas-editor';
557
+
558
+ const flowId = '123';
559
+ const apiConfig = {
560
+ scopeData: {
561
+ scope_type: 'space',
562
+ scope_value: 123,
563
+ },
564
+ };
565
+ </script>
566
+ ```
567
+
568
+ > **注意**：`defaultZoom` 的取值范围建议在 0.25 到 1.5 之间，这是 x6 画布配置的最小和最大缩放比例限制。
569
+
570
+ ### 设置 bkflow-saas-url
571
+
572
+ 可以通过 `bkflowSaasUrl` props 设置 `$.context.site_url` 的值，供插件内部使用：
573
+
574
+ ```vue
575
+ <template>
576
+ <FlowView
577
+ :flow-id="flowId"
578
+ :api-config="apiConfig"
579
+ :bkflow-saas-url="'https://example.com/bkflow'" />
580
+
581
+ <FlowEdit
582
+ :flow-id="flowId"
583
+ :api-config="apiConfig"
584
+ :bkflow-saas-url="'https://example.com/bkflow'" />
585
+
586
+ <FlowExecute
587
+ :flow-id="flowId"
588
+ :show="isExecuteShow"
589
+ :api-config="apiConfig"
590
+ :bkflow-saas-url="'https://example.com/bkflow'" />
591
+
592
+ <FlowDebug
593
+ :flow-id="flowId"
594
+ :show="isDebugShow"
595
+ :api-config="apiConfig"
596
+ :bkflow-saas-url="'https://example.com/bkflow'" />
597
+ </template>
598
+
599
+ <script setup>
600
+ import { FlowView, FlowEdit, FlowExecute, FlowDebug } from 'bkflow-canvas-editor';
601
+
602
+ const flowId = '123';
603
+ const isExecuteShow = ref(false);
604
+ const isDebugShow = ref(false);
605
+ const apiConfig = {
606
+ scopeData: {
607
+ scope_type: 'space',
608
+ scope_value: 123,
609
+ },
610
+ };
611
+ </script>
612
+ ```
613
+
614
+ > **说明**：`bkflowSaasUrl` 会被设置到 `window.$.context.site_url` 中，供插件内部使用。如果不提供，`site_url` 默认为空字符串。
615
+
459
616
  ### 使用 FlowEdit 的调试功能
460
617
 
461
618
  启用 FlowEdit 组件的调试功能，点击调试按钮会打开 FlowDebug 组件：
@@ -724,6 +881,8 @@ interface FlowApiConfig {
724
881
  组件内部会自动实现所有 API 方法，包括：
725
882
 
726
883
  - `fetchFlowDetail` - 获取流程详情
884
+ - `fetchFlowDraftDetail` - 获取流程草稿详情（可选，用于版本功能）
885
+ - `fetchFlowDetailByVersion` - 获取指定版本的流程详情（可选，用于版本功能）
727
886
  - `fetchSpaceFlowConfig` - 获取空间配置
728
887
  - `fetchSystemVariables` - 获取系统变量
729
888
  - `saveFlow` - 保存流程（仅 FlowEdit）
@@ -739,6 +898,17 @@ interface FlowApiConfig {
739
898
 
740
899
  所有 API 请求会自动合并 `scopeData` 到请求参数中。
741
900
 
901
+ ### 流程版本功能说明
902
+
903
+ 当 `enableVersion` 为 `true` 时，组件会使用版本相关的 API 来获取流程数据：
904
+
905
+ 1. **总是先调用 `fetchFlowDetail`**：获取基础流程详情数据
906
+ 2. **根据 `flowVersion` 的值决定是否调用版本接口**：
907
+ - 如果 `flowVersion` 不为空：调用 `fetchFlowDetailByVersion` 获取指定版本的 `name` 和 `pipeline_tree` 字段，覆盖基础数据
908
+ - 如果 `flowVersion` 为空：调用 `fetchFlowDraftDetail` 获取草稿版本的 `pipeline_tree` 字段，覆盖基础数据
909
+
910
+ 这种设计确保了即使在使用版本功能时，也能获取到完整的流程基础信息，同时用版本特定的数据覆盖相应字段。
911
+
742
912
  ## 类型定义
743
913
 
744
914
  所有类型定义都可以从包中导入：