@blueking/bkflow-canvas-editor 1.1.0-beta.4 → 1.1.0-beta.41

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 (22) hide show
  1. package/README.md +247 -42
  2. package/dist/advanced.cjs.js +1 -1
  3. package/dist/advanced.d.ts +473 -42
  4. package/dist/advanced.esm.js +8 -3
  5. package/dist/context-C3QIuIf6.cjs +5 -0
  6. package/dist/context-De9a4Qek.js +1507 -0
  7. package/dist/index-9BCO-loN.js +533 -0
  8. package/dist/index-A1xVRjtJ.cjs +1 -0
  9. package/dist/index-B1ybORjU.js +55768 -0
  10. package/dist/index-BwF4LXst.cjs +1 -0
  11. package/dist/index-CjCy-0c0.js +236 -0
  12. package/dist/index-RacKW0MR.js +168 -0
  13. package/dist/index-bzXGuf5c.cjs +1 -0
  14. package/dist/index-iB9uV7YQ.cjs +85 -0
  15. package/dist/index.cjs.js +1 -70
  16. package/dist/index.d.ts +969 -112
  17. package/dist/index.esm.js +48 -45880
  18. package/dist/style.css +1 -1
  19. package/dist/style.d.ts +2 -0
  20. package/package.json +13 -7
  21. package/dist/composable-CmXOtkXh.js +0 -441
  22. package/dist/composable-CtSJfiSD.cjs +0 -1
package/README.md CHANGED
@@ -5,9 +5,11 @@ bkflow流程编辑组件，支持流程的编辑、查看、调试以及创建
5
5
  ## 安装
6
6
 
7
7
  ```bash
8
- npm install @blueking/bkflow-canvas-editor
8
+ npm install @blueking/bkflow-canvas-editor @blueking/flow-canvas
9
9
  ```
10
10
 
11
+ `@blueking/flow-canvas` 是精确版本的 peerDependency，须与 editor 声明的版本一致；JS/CSS 均不打进 editor 产物。
12
+
11
13
  ## 使用
12
14
 
13
15
  ### 基础使用
@@ -24,6 +26,7 @@ npm install @blueking/bkflow-canvas-editor
24
26
 
25
27
  <script setup>
26
28
  import { FlowView } from 'bkflow-canvas-editor';
29
+ import '@blueking/flow-canvas/style';
27
30
  import 'bkflow-canvas-editor/style';
28
31
  import axios from 'axios';
29
32
 
@@ -35,6 +38,7 @@ npm install @blueking/bkflow-canvas-editor
35
38
  scopeData: {
36
39
  scope_type: 'space',
37
40
  scope_value: 123,
41
+ space_id: 123,
38
42
  }, // 作用域数据（必需）
39
43
  fetchUserApi: `${window.BK_COMPONENT_API_URL}/api/c/compapi/v2/usermanage/fs_list_users/`, // @deprecated 仅保留向后兼容，推荐使用 memberSelectorConfig
40
44
  // 可选：使用自定义 axios 实例
@@ -80,27 +84,29 @@ npm install @blueking/bkflow-canvas-editor
80
84
 
81
85
  #### Props
82
86
 
83
- | 参数 | 类型 | 默认值 | 说明 |
84
- | ------------------- | ---------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------- |
85
- | `flowId` | `string` | - | **必需**，流程 ID |
86
- | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
87
- | `permissions` | `{ canEdit?: boolean }` | `{ canEdit: true }` | 权限配置对象，`canEdit` 控制头部编辑按钮是否使用禁用样式 |
88
- | `thumbnail` | `boolean` | `false` | 小地图模式，启用后只显示画布内容，不显示顶部 header 和操作按钮，禁用节点点击事件 |
89
- | `enableVersion` | `boolean` | `false` | 是否开启流程版本功能，开启后会根据 `flowVersion` 的值获取对应版本的流程数据 |
90
- | `flowVersion` | `string` | - | 流程版本号，仅在 `enableVersion` 为 `true` 时生效。为空时表示草稿版本，不为空时表示指定版本 |
91
- | `showHeaderActions` | `boolean` | `true` | 是否显示头部操作按钮（编辑、执行流程、调试），仅在非小地图模式下生效 |
92
- | `defaultZoom` | `number` | `1` | x6 画布的默认缩放比例，用于控制画布的初始显示效果。取值范围建议在 0.25 到 1.5 之间 |
93
- | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
94
- | `onEdit` | `() => void` | - | 编辑按钮点击回调（可选，也可以通过 `@edit` 事件监听） |
95
- | `onBack` | `() => void` | - | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听） |
96
- | `onExecuteSuccess` | `(taskId: number, templateId: number) => void` | - | 执行成功回调（可选） |
87
+ | 参数 | 类型 | 默认值 | 说明 |
88
+ | ------------------- | ------------------------------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
89
+ | `flowId` | `string` | - | **必需**，流程 ID |
90
+ | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
91
+ | `permissions` | `{ canEdit?: boolean }` | `{ canEdit: true }` | 权限配置对象，`canEdit` 控制头部编辑按钮是否使用禁用样式 |
92
+ | `thumbnail` | `boolean` | `false` | 小地图模式，启用后只显示画布内容，不显示顶部 header 和操作按钮，禁用节点点击事件 |
93
+ | `enableVersion` | `boolean` | `false` | 是否开启流程版本功能，开启后会根据 `flowVersion` 的值获取对应版本的流程数据 |
94
+ | `flowVersion` | `string` | - | 流程版本号，仅在 `enableVersion` 为 `true` 时生效。为空时表示草稿版本，不为空时表示指定版本 |
95
+ | `showHeaderActions` | `boolean` | `true` | 是否显示头部操作按钮（编辑、执行流程、调试），仅在非小地图模式下生效 |
96
+ | `defaultZoom` | `number` | `1` | x6 画布的默认缩放比例，用于控制画布的初始显示效果。取值范围建议在 0.25 到 1.5 之间 |
97
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
98
+ | `hideTrigger` | `boolean` | `false` | 是否隐藏基础信息中的触发器配置表单 |
99
+ | `onEdit` | `() => void` | - | 编辑按钮点击回调（可选，也可以通过 `@edit` 事件监听） |
100
+ | `onBack` | `() => void` | - | 返回按钮点击回调（可选，也可以通过 `@back` 事件监听） |
101
+ | `onExecuteSuccess` | `(result: FlowTaskExecuteSuccessResult) => void` | - | 执行成功回调（可选），参数含 `createResult`(create_task) 与 `executeResult`(operate_task)，用 `executeResult.data.url` 跳转 |
97
102
 
98
103
  #### Slots
99
104
 
100
- | 插槽名 | 作用域参数 | 说明 |
101
- | ------------- | ---------- | ---------------------- |
102
- | `header` | - | 自定义头部内容 |
103
- | `inputParams` | 见下方说明 | 自定义节点输入参数组件 |
105
+ | 插槽名 | 作用域参数 | 说明 |
106
+ | ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
107
+ | `header` | - | 自定义头部内容 |
108
+ | `inputParams` | 见下方说明 | 自定义节点输入参数组件 |
109
+ | `customFormContent` | `customFormData`、`additionalTaskParams`、`updateCustomFormData`、`updateAdditionalTaskParams` | 创建任务侧滑自定义额外表单项；`additionalTaskParams` 会合并进创建请求 |
104
110
 
105
111
  ##### inputParams 插槽作用域参数
106
112
 
@@ -146,7 +152,8 @@ npm install @blueking/bkflow-canvas-editor
146
152
  | `defaultZoom` | `number` | `1` | x6 画布的默认缩放比例，用于控制画布的初始显示效果。取值范围建议在 0.25 到 1.5 之间 |
147
153
  | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
148
154
  | `enableThirdPlugin` | `boolean` | `true` | 是否启用第三方插件。设置为 `false` 时，将不加载第三方插件列表和详情，只显示内置插件 |
149
- | `quickAdd` | `QuickAddConfig` | - | 透传给底层画布的 quick-add 配置；默认启用，可自定义绑定端口、插入方向或显式关闭 |
155
+ | `quickAdd` | `QuickAddConfig`（来自 `@blueking/flow-canvas`） | - | 透传给底层画布的 quick-add 配置；默认启用，可自定义绑定端口、插入方向或显式关闭 |
156
+ | `hideTrigger` | `boolean` | `false` | 是否隐藏基础信息中的触发器配置表单 |
150
157
 
151
158
  #### Slots
152
159
 
@@ -192,12 +199,16 @@ npm install @blueking/bkflow-canvas-editor
192
199
  | ----------------------- | -------------------------------------------------- | ---------------------- | ---------------------------------------------------------- |
193
200
  | `updateNodeInputParams` | `inputParams: Record<string, PluginInputDataItem>` | `void` | 更新当前打开节点的输入参数（暂存，需点击确定按钮才会保存） |
194
201
  | `isFlowEdited` | - | `ComputedRef<boolean>` | 流程是否已编辑（只读） |
202
+ | `openGlobalVariables` | - | `void` | 打开全局变量面板 |
203
+ | `zoomToFit` | `options?: ZoomToFitOptions` | `void` | 自适应画布视口 |
204
+ | `centerContent` | - | `void` | 居中画布内容 |
205
+ | `getZoom` | - | `number` | 获取当前缩放比例 |
195
206
 
196
207
  ---
197
208
 
198
209
  ### SelectPanelConfig 类型
199
210
 
200
- 插件选择面板配置类型，用于配置插件选择面板中的按钮跳转链接和文本。
211
+ 插件选择面板配置类型，用于配置插件选择面板中的按钮跳转链接、文本以及标准运维插件分类白名单。
201
212
 
202
213
  #### 类型定义
203
214
 
@@ -207,6 +218,7 @@ interface SelectPanelConfig {
207
218
  agentResourceUrl?: string; // "智能体" 按钮跳转链接（可选）
208
219
  agentButtonText?: string; // "智能体" 按钮文本（可选，默认为 "智能体"）
209
220
  knowledgebaseResourceUrl?: string; // 知识库插件分组，"知识库" 按钮跳转链接（可选）
221
+ sopsCategoryWhitelist?: string; // 「标准运维插件」分组的分类白名单，分号分隔（可选）
210
222
  }
211
223
  ```
212
224
 
@@ -222,6 +234,7 @@ interface SelectPanelConfig {
222
234
  agentResourceUrl: 'https://example.com/agent',
223
235
  agentButtonText: '创建智能体',
224
236
  knowledgebaseResourceUrl: 'https://example.com/knowledgebase',
237
+ sopsCategoryWhitelist: '作业平台(JOB);配置平台(CMDB)',
225
238
  }" />
226
239
  </template>
227
240
  ```
@@ -232,6 +245,20 @@ interface SelectPanelConfig {
232
245
  - `agentButtonText` 默认值为 "智能体"
233
246
  - 配置通过 Vue 的 provide/inject 机制全局提供，子组件可以直接通过 `useSelectPanelConfig()` 获取
234
247
 
248
+ ##### sopsCategoryWhitelist
249
+
250
+ 只有命中白名单的标准运维插件分类才会出现在插件选择面板里，白名单外的分类及其插件对用户不可见。宿主一般由环境变量下发（例如 bk-incident 的 `BUITIN_PLUGINS_FILTERS` 经 html 注入到前端）：
251
+
252
+ ```vue
253
+ <FlowEdit :select-panel-config="{ sopsCategoryWhitelist: window.BUITIN_PLUGINS_FILTERS }" />
254
+ ```
255
+
256
+ - 多个分类用半角分号 `;` 分隔（全角 `；` 也可识别），每项与分类名或分类 id 精确相等（前后空格会被忽略）即命中
257
+ - 不传或传空串时展示全部分类，行为与改动前一致
258
+ - 「内置插件」与「第三方插件」两个来源共用同一份白名单
259
+ - 分类被全部过滤时该来源下展示「暂无插件分类」空态，分组和来源 tab 本身仍然显示
260
+ - 白名单只控制可选范围，已配置了白名单外插件的历史节点照常展示和编辑
261
+
235
262
  ---
236
263
 
237
264
  ### FlowCreateTask 组件
@@ -240,25 +267,31 @@ interface SelectPanelConfig {
240
267
 
241
268
  #### Props
242
269
 
243
- | 参数 | 类型 | 默认值 | 说明 |
244
- | ------------------ | ---------------------------------------------- | ------- | ------------------------------------------------------------------- |
245
- | `flowId` | `string` | - | **必需**，流程 ID |
246
- | `show` | `boolean` | - | **必需**，是否显示执行面板 |
247
- | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
248
- | `editable` | `boolean` | `true` | 是否可编辑 |
249
- | `showFlowEntry` | `boolean` | `false` | 是否显示流程入口 |
250
- | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
251
- | `onExecuteSuccess` | `(taskId: number, templateId: number) => void` | - | 执行成功回调 |
270
+ | 参数 | 类型 | 默认值 | 说明 |
271
+ | ------------------ | ------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
272
+ | `flowId` | `string` | - | **必需**，流程 ID |
273
+ | `show` | `boolean` | - | **必需**，是否显示执行面板 |
274
+ | `apiConfig` | `FlowApiConfig` | - | **必需**，API 配置对象，详见 [API 配置](#api-配置) |
275
+ | `editable` | `boolean` | `true` | 是否可编辑 |
276
+ | `showFlowEntry` | `boolean` | `false` | 是否显示流程入口 |
277
+ | `bkflowSaasUrl` | `string` | - | bkflow-saas-url，用于设置 `$.context.site_url` 的值，供插件内部使用 |
278
+ | `onExecuteSuccess` | `(result: FlowTaskExecuteSuccessResult) => void` | - | 执行成功回调，参数含 `createResult`(create_task) 与 `executeResult`(operate_task)，用 `executeResult.data.url` 跳转 |
279
+
280
+ #### Slots
281
+
282
+ | 插槽名 | Slot Props | 说明 |
283
+ | ------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
284
+ | `customFormContent` | `customFormData`、`additionalTaskParams`、`updateCustomFormData`、`updateAdditionalTaskParams` | 自定义额外表单项；`additionalTaskParams` 会合并进 `createFlowTask` |
252
285
 
253
286
  #### Events
254
287
 
255
- | 事件名 | 参数 | 说明 |
256
- | -------------- | ------------------------------------ | ------------------------ |
257
- | `confirm` | `taskId: number, templateId: number` | 执行确认时触发 |
258
- | `close` | - | 关闭面板时触发 |
259
- | `update:show` | `show: boolean` | 显示状态更新时触发 |
260
- | `before-close` | - | 面板关闭前触发 |
261
- | `view-flow` | - | 点击查看排障流程按钮触发 |
288
+ | 事件名 | 参数 | 说明 |
289
+ | -------------- | -------------------------------------- | ------------------------ |
290
+ | `confirm` | `result: FlowTaskExecuteSuccessResult` | 执行确认时触发 |
291
+ | `close` | - | 关闭面板时触发 |
292
+ | `update:show` | `show: boolean` | 显示状态更新时触发 |
293
+ | `before-close` | - | 面板关闭前触发 |
294
+ | `view-flow` | - | 点击查看排障流程按钮触发 |
262
295
 
263
296
  ---
264
297
 
@@ -340,6 +373,114 @@ interface SelectPanelConfig {
340
373
 
341
374
  ---
342
375
 
376
+ ### FlowDetail 组件
377
+
378
+ 统一的流程详情组件，将「查看 / 编辑 / 调试」收敛到一个入口，通过 `permissions` 精确控制能力。推荐新接入方使用 `FlowDetail` 替代 `FlowMockDebug`。
379
+
380
+ > `FlowDetail` 仅支持 Vue 3。`FlowEdit` / `FlowView` 的既有行为、Props/Emits 不受影响，可继续使用。
381
+
382
+ #### 安装与基础示例
383
+
384
+ ```vue
385
+ <template>
386
+ <FlowDetail
387
+ :flow-id="flowId"
388
+ :api-config="apiConfig"
389
+ :permissions="{ canEdit: true, canDebug: true, canExecute: true }"
390
+ @save="handleSave"
391
+ @back="handleBack" />
392
+ </template>
393
+
394
+ <script setup>
395
+ import { FlowDetail } from '@blueking/bkflow-canvas-editor';
396
+ import '@blueking/flow-canvas/style';
397
+ import '@blueking/bkflow-canvas-editor/style';
398
+
399
+ const flowId = '2085';
400
+ const apiConfig = {
401
+ scopeData: { scope_type: 'space', scope_value: 171, space_id: 171 },
402
+ };
403
+ </script>
404
+ ```
405
+
406
+ #### Props
407
+
408
+ | 参数 | 类型 | 默认值 | 说明 |
409
+ | ------------- | --------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
410
+ | `flowId` | `string` | - | **必需**，流程 ID |
411
+ | `apiConfig` | `FlowApiConfig \| FlowDetailApiConfig` | - | **必需**，API 配置对象；`canDebug=true` 时需一并提供调试方法（见下） |
412
+ | `permissions` | `Partial<FlowDetailPermissions>` | `{ canEdit: false, canDebug: false, canExecute: false }` | 权限配置，**默认全部拒绝**，需显式开启 |
413
+ | `onExecuteSuccess` | `(result: FlowTaskExecuteSuccessResult) => void` | - | 执行成功回调，参数与 `FlowView` 一致 |
414
+ | `enableVersion` / `flowVersion` | `boolean` / `string` | `false` / - | 流程版本功能，语义与 FlowView/FlowEdit 一致 |
415
+ | `defaultZoom` / `quickAdd` / `hideTrigger` / `bkflowSaasUrl` | 同 FlowEdit | - | 透传给内部画布与信息侧滑 |
416
+
417
+ #### Events
418
+
419
+ | 事件名 | 参数 | 说明 |
420
+ | ------------- | ------------------------ | -------------------------- |
421
+ | `save` | `flowData: FlowTemplate` | 显式保存成功后触发 |
422
+ | `saveSuccess` | - | 显式保存成功后触发 |
423
+ | `back` | - | 返回按钮点击时触发 |
424
+ | `createVariable` | `{ keyword, cursorIndex }` | 请求新建全局变量时触发 |
425
+
426
+ #### Slots
427
+
428
+ | 插槽名 | 作用域参数 | 说明 |
429
+ | ------------------ | ------------------------------------------- | ---------------------------------------------------------------------- |
430
+ | `header` | - | 自定义头部左侧标题区 |
431
+ | `headerActions` | `{ savePending, canMutateFlow }` | 头部右侧操作区追加宿主自定义按钮，排在内置「保存」「执行流程」之后 |
432
+ | `inputParams` | 见 `FlowView` | 自定义节点输入参数表单 |
433
+ | `customFormContent`| 见 `FlowView` | 自定义创建任务侧滑表单内容 |
434
+
435
+ #### 权限矩阵
436
+
437
+ `permissions` 默认拒绝，四种组合如下：
438
+
439
+ | `canEdit` | `canDebug` | 效果 |
440
+ | --------- | ---------- | ---------------------------------------------------------- |
441
+ | `false` | `false` | 纯只读查看，无保存、无调试入口，且**不请求任何调试接口** |
442
+ | `true` | `false` | 可编辑与保存，无调试入口 |
443
+ | `false` | `true` | 只读画布 + 全流程/单节点调试（调试期间流程本就不可编辑） |
444
+ | `true` | `true` | 可编辑、保存与完整调试；调试运行中锁定编辑（画布转 `view`）|
445
+
446
+ `permissions.canExecute` 独立控制头部“执行流程”按钮的显示，为 `false` 时按钮不渲染。流程存在未保存修改时，确认保存成功后才会打开创建任务侧滑；`customFormContent` 插槽与 `FlowView` 一致。
447
+
448
+ 头部右侧按钮区在 `canEdit`、`canExecute` 均为 `false` 且未传 `headerActions` 插槽时整体不渲染。宿主若要按状态控制自定义按钮的显隐，可在插槽模板上直接加 `v-if`，插槽未传入时按钮区不会留下空白：
449
+
450
+ ```vue
451
+ <FlowDetail :flow-id="flowId" :api-config="apiConfig" :permissions="permissions">
452
+ <template v-if="permissions.canEdit" #headerActions>
453
+ <bk-button @click="handleExitEdit">退出编辑</bk-button>
454
+ </template>
455
+ </FlowDetail>
456
+ ```
457
+
458
+ #### 调试能力
459
+
460
+ - **全流程调试**：头部调试入口填写全局输入后启动，前端按 2500ms（失败退避 5000ms）轮询 `/context/`，可随时终止。
461
+ - **单节点 real**：节点详情「调试配置」Tab 内直接以真实逻辑同步执行单步，完成后刷新 `context`。
462
+ - **单节点 Mock**：配置 Mock 输出结果后执行（内部顺序：保存 Mock → 单步执行 mock）；执行时跳过该节点并以 Mock 输出替代实际输出，Mock 节点在后续全流程中保留 `MOCK` 标签。
463
+ - **取消 Mock**：清除节点的持久 Mock 配置。
464
+ - **终止**：全流程终止不传 `node_id`；单步调试进入运行/等待态时，传当前 `active_node_id` 终止该节点。
465
+ - **保存联动**：`canDebug` 且 `context` 空闲时，保存成功后会查询 `reset_impact` 并自动清理失效节点的调试结果。
466
+
467
+ #### 调试 API 契约（`canDebug=true` 必需）
468
+
469
+ 消费方若传入完整的 api 配置对象（而非仅 `scopeData`），当 `canDebug=true` 时**必须**一并提供以下调试方法，组件初始化时会统一校验：
470
+
471
+ `fetchDebugContext`、`fetchDebugInputSchema`、`fetchDebugResetImpact`、`updateNodeDebugMock`、`runNodeDebugStep`、`runGlobalDebug`、`terminateDebug`、`resetDebugResult`（签名见 `DebugApiServices`）。
472
+
473
+ 约定：
474
+
475
+ - 前端以 `debug_context`（后端 `build_context_view`）为**唯一事实源**，不新增 `node_input_values` 接口。`active_*`（当前持锁任务）与 `last_*`（最近一次运行）按顶层 `status` 分支选用。
476
+ - 建议后端在 `debug_context` 透出 `mock_outputs` / `mock_error` / `outputs`，否则刷新后 Mock 输出与「输出结果/重新编辑」回填会缺数据。
477
+ - 调试接口与普通接口同源：走后端 python 包 bkflow_sdk `TemplateViewSet` 的 `/bkflow/template/debug_*`，全站信封 `{result, data, message}`。走内置 `useFlowApi()` 时自动获得全部调试方法。
478
+ - 调试与普通接口共用同一 ApiClient：只在客户端边界解信封，并统一抛出 `ApiError`。调试请求的 `delegate` 仅转交 Message 呈现权，service/controller/page 不再重复解包或改造错误。
479
+
480
+ > **Deprecated**：`FlowMockDebug` 已废弃，请改用 `FlowDetail` 并开启 `permissions.canDebug`。`FlowMockDebug` 将在下个大版本移除。
481
+
482
+ ---
483
+
343
484
  ## 使用示例
344
485
 
345
486
  ### 基础使用
@@ -364,6 +505,7 @@ interface SelectPanelConfig {
364
505
  scopeData: {
365
506
  scope_type: 'space',
366
507
  scope_value: 123,
508
+ space_id: 123,
367
509
  },
368
510
  };
369
511
 
@@ -427,6 +569,7 @@ interface SelectPanelConfig {
427
569
  scopeData: {
428
570
  scope_type: "space",
429
571
  scope_value: 123,
572
+ space_id: 123,
430
573
  },
431
574
  };
432
575
 
@@ -459,11 +602,14 @@ interface SelectPanelConfig {
459
602
  scopeData: {
460
603
  scope_type: 'space',
461
604
  scope_value: 123,
605
+ space_id: 123,
462
606
  },
463
607
  };
464
608
  </script>
465
609
  ```
466
610
 
611
+ 外部 Axios 实例仍会通过组件的统一 ApiClient 边界，因此无论宿主拦截器返回 `AxiosResponse`、信封 body 或已解包 DTO，组件内部都获得业务 DTO。建议宿主拦截器不要再对 `{ result: false }` 弹业务 Message，否则无法保证跨边界的单次呈现。
612
+
467
613
  ### 监听流程编辑状态
468
614
 
469
615
  ```vue
@@ -514,6 +660,7 @@ interface SelectPanelConfig {
514
660
 
515
661
  <script setup>
516
662
  import { FlowView } from 'bkflow-canvas-editor';
663
+ import '@blueking/flow-canvas/style';
517
664
  import 'bkflow-canvas-editor/style';
518
665
 
519
666
  const flowId = '123';
@@ -521,6 +668,7 @@ interface SelectPanelConfig {
521
668
  scopeData: {
522
669
  scope_type: 'space',
523
670
  scope_value: 123,
671
+ space_id: 123,
524
672
  },
525
673
  };
526
674
  </script>
@@ -563,6 +711,7 @@ interface SelectPanelConfig {
563
711
  scopeData: {
564
712
  scope_type: 'space',
565
713
  scope_value: 123,
714
+ space_id: 123,
566
715
  },
567
716
  };
568
717
  </script>
@@ -586,6 +735,7 @@ interface SelectPanelConfig {
586
735
  scopeData: {
587
736
  scope_type: 'space',
588
737
  scope_value: 123,
738
+ space_id: 123,
589
739
  },
590
740
  };
591
741
  </script>
@@ -612,6 +762,7 @@ interface SelectPanelConfig {
612
762
  scopeData: {
613
763
  scope_type: 'space',
614
764
  scope_value: 123,
765
+ space_id: 123,
615
766
  },
616
767
  };
617
768
  </script>
@@ -682,6 +833,7 @@ interface SelectPanelConfig {
682
833
  scopeData: {
683
834
  scope_type: 'space',
684
835
  scope_value: 123,
836
+ space_id: 123,
685
837
  },
686
838
  };
687
839
  </script>
@@ -706,6 +858,7 @@ interface SelectPanelConfig {
706
858
  scopeData: {
707
859
  scope_type: 'space',
708
860
  scope_value: 123,
861
+ space_id: 123,
709
862
  },
710
863
  };
711
864
  </script>
@@ -758,6 +911,7 @@ interface SelectPanelConfig {
758
911
  scopeData: {
759
912
  scope_type: 'space',
760
913
  scope_value: 123,
914
+ space_id: 123,
761
915
  },
762
916
  };
763
917
 
@@ -797,6 +951,7 @@ interface SelectPanelConfig {
797
951
  scopeData: {
798
952
  scope_type: 'space',
799
953
  scope_value: 123,
954
+ space_id: 123,
800
955
  },
801
956
  };
802
957
 
@@ -840,6 +995,7 @@ interface SelectPanelConfig {
840
995
  scopeData: {
841
996
  scope_type: 'space',
842
997
  scope_value: 123,
998
+ space_id: 123,
843
999
  },
844
1000
  };
845
1001
  </script>
@@ -879,6 +1035,7 @@ interface SelectPanelConfig {
879
1035
  scopeData: {
880
1036
  scope_type: 'space',
881
1037
  scope_value: 123,
1038
+ space_id: 123,
882
1039
  },
883
1040
  };
884
1041
  </script>
@@ -907,6 +1064,7 @@ interface SelectPanelConfig {
907
1064
  scopeData: {
908
1065
  scope_type: 'space',
909
1066
  scope_value: 123,
1067
+ space_id: 123,
910
1068
  },
911
1069
  };
912
1070
 
@@ -947,6 +1105,7 @@ interface SelectPanelConfig {
947
1105
  scopeData: {
948
1106
  scope_type: 'space',
949
1107
  scope_value: 123,
1108
+ space_id: 123,
950
1109
  },
951
1110
  };
952
1111
 
@@ -993,6 +1152,7 @@ interface SelectPanelConfig {
993
1152
  scopeData: {
994
1153
  scope_type: 'space',
995
1154
  scope_value: 123,
1155
+ space_id: 123,
996
1156
  },
997
1157
  };
998
1158
  </script>
@@ -1018,6 +1178,8 @@ interface FlowApiConfig {
1018
1178
  scopeData: {
1019
1179
  scope_type: string;
1020
1180
  scope_value: number;
1181
+ /** 业务方传入的空间 ID，调试接口专用，语义独立于 scope_value */
1182
+ space_id: number;
1021
1183
  };
1022
1184
  /**
1023
1185
  * 用户查询 API 地址
@@ -1100,7 +1262,7 @@ type MemberSelectorConfig =
1100
1262
 
1101
1263
  ### 高级用法：传入完整 API 方法对象
1102
1264
 
1103
- 深度集成场景下，组件也支持直接传入“已处理好的 API 方法对象”。这类对象通常通过 `useFlowApi` 生成，或在其基础上覆写单个方法。
1265
+ 深度集成场景下，组件也支持直接传入“已处理好的 API 方法对象”。这类对象通常通过 `useFlowApi` 生成，或在其基础上覆写单个方法。“已处理”的契约是：方法直接 resolve 类型声明中的业务 DTO，失败时 reject `Error`/`ApiError`，不要再返回 `AxiosResponse` 或 `{ result, data, message }` 信封。
1104
1266
 
1105
1267
  - 常规场景：直接传 `FlowApiConfig`
1106
1268
  - 高级场景：传 `useFlowApi(config)` 的返回值
@@ -1117,6 +1279,7 @@ const baseConfig: FlowApiConfig = {
1117
1279
  scopeData: {
1118
1280
  scope_type: 'space',
1119
1281
  scope_value: 123,
1282
+ space_id: 123,
1120
1283
  },
1121
1284
  fetchUserApi: `${window.BK_COMPONENT_API_URL}/api/c/compapi/v2/usermanage/fs_list_users/`,
1122
1285
  };
@@ -1127,7 +1290,8 @@ const apiConfig: FlowViewApiConfig = {
1127
1290
  const res = await http.get(`/custom/template/${id}/detail/`, {
1128
1291
  params: baseConfig.scopeData,
1129
1292
  });
1130
- return res.data;
1293
+ // 此处是宿主适配边界：返回 FlowTemplate，不返回 AxiosResponse/信封。
1294
+ return res.data.data;
1131
1295
  },
1132
1296
  };
1133
1297
  ```
@@ -1174,10 +1338,11 @@ import type {
1174
1338
  UniformApiPluginInputsItem,
1175
1339
  PluginDetailCommon,
1176
1340
  SelectPanelConfig,
1177
- QuickAddConfig,
1178
- InsertDirection,
1179
1341
  // ... 更多类型
1180
1342
  } from 'bkflow-canvas-editor';
1343
+
1344
+ // 引擎类型从 @blueking/flow-canvas 导入，本包不再再导出
1345
+ import type { QuickAddConfig, InsertDirection } from '@blueking/flow-canvas';
1181
1346
  ```
1182
1347
 
1183
1348
  高级集成场景下，还可以从 `@blueking/bkflow-canvas-editor/advanced` 导入完整 API 类型和 `useFlowApi`：
@@ -1218,7 +1383,7 @@ resolve: {
1218
1383
  4. **自动合并 scopeData**：所有 API 请求会自动合并 `scopeData` 到请求参数中（GET 请求合并到 params，POST/PUT 请求合并到请求体）
1219
1384
  5. **权限检查**：权限检查通过 `permissions` props 传入布尔值
1220
1385
  6. **路由跳转**：路由跳转需要通过事件回调处理，组件内部不直接使用 vue-router
1221
- 7. **样式引入**：样式文件需要单独引入：`import 'bkflow-canvas-editor/style'`
1386
+ 7. **样式引入**：需分别引入引擎与业务样式：`import '@blueking/flow-canvas/style'` 与 `import 'bkflow-canvas-editor/style'`
1222
1387
  8. **输入参数更新机制**：
1223
1388
  - 使用 `inputParams` 插槽时，通过 `updateInputParams` 或 `updateNodeInputParams` 方法更新的数据会暂存到节点配置面板
1224
1389
  - 用户需要点击节点配置面板的"确定"按钮，数据才会真正保存到流程中
@@ -1237,6 +1402,46 @@ resolve: {
1237
1402
  - FlowEdit 会自动将版本相关 props 透传给内嵌的 FlowDebug 组件
1238
1403
  - 版本功能依赖 `fetchFlowDraftDetail` 和 `fetchFlowDetailByVersion` 两个 API 方法
1239
1404
 
1405
+ ## 国际化
1406
+
1407
+ 包内自带 `zh-cn` 与 `en` 词条，默认 `zh-cn`。宿主在挂载前调用一次 `setLocale` 即可：
1408
+
1409
+ ```typescript
1410
+ import { setLocale } from '@blueking/bkflow-canvas-editor';
1411
+
1412
+ setLocale('en');
1413
+ ```
1414
+
1415
+ 语言是进程级全局状态，切换后需由宿主刷新页面；不支持同一页面内两个画布实例使用不同语言。
1416
+
1417
+ 组件库（bkui-vue / element-plus）的文案由包内自动联动，宿主无需在 `app.use(bkui)` 时额外配置。
1418
+
1419
+ `setLocale` 只管前端文案。**后端下发的内容（插件名称、插件表单 schema 标签、接口报错）
1420
+ 不受它影响**——bkflow 后端按 `blueking_language` Cookie（`zh-cn` / `en`）判定语言，
1421
+ 不读 `Accept-Language` 请求头，宿主需自行设置该 Cookie。
1422
+
1423
+ locale 非 `zh-cn` 时本包会改写 bkui-vue 的 `defaultRootConfig.locale` 以覆盖命令式
1424
+ `Message` / `InfoBox`，**影响范围是整个宿主应用**。详见
1425
+ [docs/usage.md 的国际化章节](./docs/usage.md#国际化)。
1426
+
1427
+ 进阶用法：
1428
+
1429
+ | API | 用途 |
1430
+ | --- | --- |
1431
+ | `registerMessages(locale, messages, options?)` | 深合并覆盖个别词条，或注册包内没有的新语言 |
1432
+ | `setTranslator(fn)` | 完全接管翻译，桥接宿主已有的 i18n；返回 `undefined` 时回落包内词条 |
1433
+ | `getLocale()` | 读取当前语言 |
1434
+
1435
+ 注册新语言时可一并提供 bkui-vue 语言包：
1436
+
1437
+ ```typescript
1438
+ import { registerMessages } from '@blueking/bkflow-canvas-editor';
1439
+ import jaMessages from './ja';
1440
+ import { jp } from 'bkui-vue/lib/locale';
1441
+
1442
+ registerMessages('ja', jaMessages, { bkuiLocale: jp });
1443
+ ```
1444
+
1240
1445
  ## License
1241
1446
 
1242
1447
  MIT
package/dist/advanced.cjs.js CHANGED
@@ -1 +1 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./composable-CtSJfiSD.cjs");exports.PLUGIN_GROUP_ICON_MAP=e.PLUGIN_GROUP_ICON_MAP;exports.useFlowApi=e.useFlowApi;
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./context-C3QIuIf6.cjs");exports.PLUGIN_GROUP_ICON_MAP=e.PLUGIN_GROUP_ICON_MAP;exports.SOPS_PLUGIN_GROUP_NAME=e.SOPS_PLUGIN_GROUP_NAME;exports.provideVariableInputCreateVariable=e.provideVariableInputCreateVariable;exports.resolveSopsPluginSources=e.resolveSopsPluginSources;exports.useFlowApi=e.useFlowApi;exports.useVariableInputCreateVariable=e.useVariableInputCreateVariable;exports.withSopsPluginGroup=e.withSopsPluginGroup;