@blueking/bkflow-canvas-editor 1.0.3 → 1.1.0-beta.1

package/README.md

@@ -1010,7 +1010,7 @@ interface FlowApiConfig {
 }
 ```
 
-组件内部会自动实现所有 API 方法，包括：
+`FlowApiConfig` 是常规场景下推荐传入的初始化配置。组件内部会基于它自动创建完整的 API 方法集合，包括：
 
 - `fetchFlowDetail` - 获取流程详情
 - `fetchFlowDraftDetail` - 获取流程草稿详情（可选，用于版本功能）
@@ -1030,6 +1030,50 @@ interface FlowApiConfig {
 
 所有 API 请求会自动合并 `scopeData` 到请求参数中。
 
+### 高级用法：传入完整 API 方法对象
+
+深度集成场景下，组件也支持直接传入“已处理好的 API 方法对象”。这类对象通常通过 `useFlowApi` 生成，或在其基础上覆写单个方法。
+
+- 常规场景：直接传 `FlowApiConfig`
+- 高级场景：传 `useFlowApi(config)` 的返回值
+- 自定义接口场景：先 `useFlowApi(config)`，再覆写需要替换的方法，例如 `fetchFlowDetail`
+
+示例：自定义“获取流程详情”接口
+
+```typescript
+import type { FlowApiConfig } from '@blueking/bkflow-canvas-editor';
+import { useFlowApi, type FlowViewApiConfig } from '@blueking/bkflow-canvas-editor/advanced';
+
+const baseConfig: FlowApiConfig = {
+  axiosInstance: http,
+  scopeData: {
+    scope_type: 'space',
+    scope_value: 123,
+  },
+  fetchUserApi: `${window.BK_COMPONENT_API_URL}/api/c/compapi/v2/usermanage/fs_list_users/`,
+};
+
+const apiConfig: FlowViewApiConfig = {
+  ...useFlowApi(baseConfig),
+  async fetchFlowDetail(id: string) {
+    const res = await http.get(`/custom/template/${id}/detail/`, {
+      params: baseConfig.scopeData,
+    });
+    return res.data;
+  },
+};
+```
+
+```vue
+<FlowView :flow-id="flowId" :api-config="apiConfig" />
+```
+
+> **注意**：
+>
+> - `FlowView` 推荐使用 `FlowViewApiConfig`
+> - `FlowEdit` / `FlowCreateTask` / `FlowDebug` 推荐使用 `FlowEditApiConfig`
+> - 如果开启版本功能，自定义 API 对象还需要同时提供 `fetchFlowDraftDetail` 和 `fetchFlowDetailByVersion`
+
 ### 流程版本功能说明
 
 当 `enableVersion` 为 `true` 时，FlowView、FlowEdit 和 FlowDebug 组件会使用版本相关的 API 来获取流程数据：
@@ -1068,7 +1112,13 @@ import type {
 } from 'bkflow-canvas-editor';
 ```
 
-> **注意**：`FlowViewApiConfig` 和 `FlowEditApiConfig` 是组件内部使用的类型，外部使用者只需要使用 `FlowApiConfig`。组件内部会通过 `useFlowApi` 自动将 `FlowApiConfig` 转换为所需的 API 方法接口。
+高级集成场景下，还可以从 `@blueking/bkflow-canvas-editor/advanced` 导入完整 API 类型和 `useFlowApi`：
+
+```typescript
+import { useFlowApi, type FlowViewApiConfig, type FlowEditApiConfig } from '@blueking/bkflow-canvas-editor/advanced';
+```
+
+> **注意**：常规使用只需要 `FlowApiConfig`。`FlowViewApiConfig`、`FlowEditApiConfig` 和 `useFlowApi` 适用于需要覆写单个接口或深度集成组件内部 API 的场景。
 
 ## 本地开发
 
@@ -1095,7 +1145,7 @@ resolve: {
 ## 注意事项
 
 1. **scopeData 必需**：`scopeData` 是必需的配置项，必须由外部传入，组件内部不会处理或设置默认值
-2. **API 自动处理**：所有 API 调用由组件内部自动处理，无需手动实现 API 方法
+2. **API 自动处理**：默认情况下，所有 API 调用都由组件基于 `FlowApiConfig` 自动生成；深度集成场景下，也可以传入完整 API 方法对象来自定义单个接口
 3. **axios 实例优先级**：如果提供了 `axiosInstance`，组件会优先使用该实例；否则会根据 `baseURL` 和 `axiosConfig` 创建新的 axios 实例
 4. **自动合并 scopeData**：所有 API 请求会自动合并 `scopeData` 到请求参数中（GET 请求合并到 params，POST/PUT 请求合并到请求体）
 5. **权限检查**：权限检查通过 `permissions` props 传入布尔值
@@ -1106,9 +1156,10 @@ resolve: {
    - 用户需要点击节点配置面板的"确定"按钮，数据才会真正保存到流程中
    - 这种设计允许用户在保存前多次修改和预览
 9. **API 配置类型说明**：
-   - 外部使用者只需要使用 `FlowApiConfig` 类型
-   - `FlowViewApiConfig` 和 `FlowEditApiConfig` 是组件内部使用的类型，通过 `useFlowApi` 自动转换
-   - `FlowCreateTask` 和 `FlowDebug` 组件可以直接接受 `FlowApiConfig` 类型，组件内部会自动处理
+   - 常规场景推荐使用 `FlowApiConfig`
+   - 需要覆写 `fetchFlowDetail` 等单个接口时，可以使用 `useFlowApi`
+   - `FlowViewApiConfig` 和 `FlowEditApiConfig` 从 `@blueking/bkflow-canvas-editor/advanced` 导出，适用于深度集成场景
+   - `FlowCreateTask` 和 `FlowDebug` 也支持上述 API 配置方式
 10. **调试功能**：
     - `FlowEdit` 组件的 `enableDebug` props 默认为 `false`，设置为 `true` 后才会显示可点击的调试按钮
     - 点击调试按钮会打开 `FlowDebug` 组件，该组件提供了与 `FlowCreateTask` 相同的交互，但支持自定义表单插槽和自定义确定按钮回调

package/dist/advanced.d.ts

@@ -163,13 +163,25 @@ interface Variable {
   show_type: 'show' | 'hide';
   source_info: Record<string, string[]>;
   source_tag: string;
-  source_type: 'custom' | 'component_inputs' | 'component_outputs' | 'system';
+  source_type: 'custom' | 'component_inputs' | 'component_outputs' | 'system' | 'space';
   validation: string;
-  value?: string | number | boolean | Record<string, any>;
+  value?: string | number | boolean | Record<string, any> | any[];
   version?: string;
   form_schema?: Record<string, any>;
   pre_render_mako?: boolean;
   plugin_code?: string;
+  /**
+   * 全局变量改版后新增字段，前端自管。
+   * 用于存储「组件配置」区域的扩展字段（如 required、data_type、placeholder、validation_error_msg），
+   * 后端原样透传即可。
+   */
+  meta?: {
+    required?: boolean;
+    data_type?: string;
+    placeholder?: string;
+    validation_error_msg?: string;
+    [key: string]: any;
+  };
 }
 
 interface PipelineTree {