@blueking/flow-canvas 0.0.1-beta.4 → 0.0.2

package/README.md

@@ -81,6 +81,7 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
     CanvasRuntime,
     CanvasLayout,
     CanvasToolbar,
+    createBuiltinEdgeTypes,
     selectionPlugin,
     snaplinePlugin,
     connectionValidatorPlugin,
@@ -91,24 +92,19 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
   import '@blueking/flow-canvas/style';
   import MyTaskNode from './components/my-task-node.vue';
 
+  const builtinEdgeTypes = createBuiltinEdgeTypes();
+
   const schema: CanvasSchema = {
     nodeTypes: {
       task: {
         component: MyTaskNode,
         getSize: () => ({ width: 180, height: 60 }),
-        getPorts: () => [
-          { id: 'left', group: 'left' },
-          { id: 'right', group: 'right' },
-        ],
       },
     },
     edgeTypes: {
-      default: {
-        router: { name: 'manhattan', args: { padding: 10 } },
-        connector: 'rounded',
-      },
+      bezier: builtinEdgeTypes.bezier,
     },
-    defaultEdgeType: 'default',
+    defaultEdgeType: 'bezier',
   };
 
   const initialFlowModel: FlowModel = {
@@ -152,6 +148,8 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
 </script>
 ```
 
+这个示例刻意省略了 `getPorts`，因为当前版本在未提供 `getPorts` / `node.ports` 时会自动补齐默认四向端口，普通自定义节点通常只需要关注 `component` 和 `getSize`。
+
 <br>
 
 ## 核心 API
@@ -205,7 +203,7 @@ interface FlowNodeModel {
   type: string; // 对应 schema.nodeTypes 的 key
   position: { x: number; y: number };
   label?: string;
-  ports?: FlowPortModel[];
+  ports?: FlowPortModel[]; // 业务自定义端口；未提供 getPorts() 时优先读取，缺省时引擎自动补四向默认端口
   payload?: Record<string, unknown>; // 业务数据
   extensions?: Record<string, unknown>; // 扩展数据
 }
@@ -239,6 +237,30 @@ interface CanvasNodeDefinition {
 
 节点 Vue 组件内可通过 `inject('getNode')` 获取 X6 Node 实例，读取 `node.getData()` 访问 `FlowNodeModel`。
 
+#### 端口来源与 `getPorts` 选型
+
+`getSize` 是必填；`getPorts` 和 `getBehavior` 都是可选。
+
+运行时解析节点端口的优先级如下：
+
+1. `definition.getPorts(node)`
+2. `node.ports`
+3. 默认四向端口（top/right/bottom/left）
+
+这意味着：
+
+- 不写 `getPorts` 且 `node.ports` 也未提供时，引擎会自动补一套默认四向端口，位置位于四条边中点
+- 默认 quick-add 会直接绑定到这套默认端口中的 `group: 'right'`，因此普通自定义节点只定义 `component/getSize/getBehavior` 也能保持默认右侧交互
+- 引擎内置的是四个方向端口组的默认位置和样式模板；默认兜底端口也复用这套约定
+- 如果你想显式禁用端口，需要返回空数组，例如 `getPorts: () => []` 或设置 `node.ports = []`
+
+推荐使用方式：
+
+- 端口结构按节点类型固定时，用 `getPorts`
+- 端口结构需要根据当前节点数据动态计算时，用 `getPorts`
+- 端口本身属于业务数据、需要随 `FlowModel` 持久化或导入导出时，用 `node.ports`
+- 如果同时提供了 `getPorts` 和 `node.ports`，运行时以前者为准
+
 ### 边类型定义
 
 ```typescript
@@ -347,6 +369,27 @@ const { schema, paletteItems } = createDefaultSchema({
 });
 ```
 
+**在自定义 Schema 中复用内置边类型：**
+
+当你没有使用 `createDefaultSchema()`，而是像适配层那样手写 `CanvasSchema` 时，可以通过 `createBuiltinEdgeTypes()` 直接复用引擎内置的 `manhattan` / `bezier` 定义，避免在业务包里重复拷贝一份。
+
+```typescript
+import { createBuiltinEdgeTypes, type CanvasSchema } from '@blueking/flow-canvas';
+
+const builtinEdgeTypes = createBuiltinEdgeTypes();
+
+const schema: CanvasSchema = {
+  nodeTypes: {
+    /* ... */
+  },
+  edgeTypes: {
+    default: { ...builtinEdgeTypes.manhattan, labelDraggable: true },
+    ...builtinEdgeTypes,
+  },
+  defaultEdgeType: 'bezier',
+};
+```
+
 **手动定义边类型（不使用 `createDefaultSchema`）：**
 
 在手动编写 `CanvasSchema` 时，同样可以通过 `edgeTypes` 和 `defaultEdgeType` 配置连线样式：
@@ -611,7 +654,7 @@ if (result.status === 'applied') {
 | editor       | `CanvasEditorContext`     | 编辑器实例（必填）                         |
 | graphOptions | `Record<string, unknown>` | 额外 X6 Graph 选项                         |
 | nodeActions  | `NodeActionsConfig`       | 节点快捷操作工具栏配置（见下方详细说明）   |
-| quickAdd     | `QuickAddConfig`          | 右侧端口快捷添加按钮配置（见下方详细说明） |
+| quickAdd     | `QuickAddConfig`          | 快捷添加按钮配置（默认绑定右侧端口，见下方详细说明） |
 
 | Emit     | 参数            | 说明                 |
 | -------- | --------------- | -------------------- |
@@ -619,7 +662,7 @@ if (result.status === 'applied') {
 
 | Slot            | Props                                            | 说明                                                        |
 | --------------- | ------------------------------------------------ | ----------------------------------------------------------- |
-| quick-add-panel | `{ node, api, insertNodeToRight, closePopover }` | 快捷添加弹层内容，点击右侧"+"按钮时显示（默认显示提示文字） |
+| quick-add-panel | `{ node, api, insertNodeToRight, closePopover }` | 快捷添加弹层内容，点击绑定端口上的"+"按钮时显示（默认显示提示文字） |
 
 #### 节点快捷操作工具栏
 
@@ -665,10 +708,10 @@ if (result.status === 'applied') {
 
 #### 节点快捷添加按钮（Quick Add）
 
-hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和拖拽发起连线。通过 `quickAdd` prop 进行全局配置：
+hover 节点时，指定端口会显示为"+"按钮，支持点击弹出面板和拖拽发起连线。默认绑定右侧 `group: 'right'` 端口。通过 `quickAdd` prop 进行全局配置：
 
 ```html
-<CanvasRuntime :editor="editor" :quick-add="{ enabled: true }">
+<CanvasRuntime :editor="editor" :quick-add="{ enabled: true, portGroup: 'right' }">
   <template #quick-add-panel="{ node, api, insertNodeToRight, closePopover }">
     <!-- 自定义节点选择面板 -->
   </template>
@@ -677,10 +720,13 @@ hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和
 
 **QuickAddConfig（全局配置）**
 
-| 属性          | 类型      | 默认   | 说明                                    |
-| ------------- | --------- | ------ | --------------------------------------- |
-| `enabled`     | `boolean` | `true` | 全局开关                                |
-| `tooltipText` | `string`  | `''`   | 自定义 tooltip 文案（空值使用内置提示） |
+| 属性          | 类型      | 默认      | 说明                                                           |
+| ------------- | --------- | --------- | -------------------------------------------------------------- |
+| `enabled`     | `boolean` | `true`    | 全局开关                                                       |
+| `tooltipText` | `string`  | `''`      | 自定义 tooltip 文案（空值使用内置提示）                        |
+| `portGroup`   | `string`  | `'right'` | quick-add 默认绑定的端口分组；节点不存在该分组端口时不显示 quick-add |
+| `getPort`     | `function` | -        | 精确指定当前节点使用哪个 port；优先级高于 `portGroup` |
+| `insertDirection` | `string \| function` | - | 点击 quick-add 插入节点时使用的方向；默认跟随当前绑定 port 的标准方向，不可推断时回退为 `'right'` |
 
 **NodeBehaviorConfig 中的快捷添加相关字段（逐节点控制）**
 
@@ -690,13 +736,51 @@ hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和
 
 生效规则：显示 = `global.enabled !== false` AND `perNode.quickAddEnabled !== false`。
 
+对于未显式提供 `getPorts` / `node.ports` 的自定义节点，quick-add 会落到引擎自动补齐的默认四向端口上，因此默认右侧交互仍然可用。
+
+`getPort(node, ports)` 优先级高于 `portGroup`，适合一个节点存在多个同分组 port，或端口选择依赖节点数据的场景。
+
+`insertDirection` 用于控制点击 quick-add 后的插入方向：
+
+- 不传时：优先跟随当前绑定 port 的标准方向（`top/right/bottom/left`）
+- 如果当前绑定 port 不是标准方向：回退为 `'right'`
+- 传字符串时：固定使用该方向
+- 传函数时：可根据节点和当前绑定 port 动态决定方向
+
+`portGroup` / `getPort` 只控制 quick-add 绑定到哪个端口、"+"按钮显示在哪个端口上，以及拖拽从哪个端口发起。
+
+slot 中提供的 `insertNodeToRight` helper 出于兼容仍保留这个名字，但它现在会遵循 `insertDirection` 的配置，不再总是向右插入。
+
+**自定义 quick-add 端口选择：**
+
+```vue
+<CanvasRuntime
+  :editor="editor"
+  :quick-add="{
+    enabled: true,
+    portGroup: 'right',
+    getPort: (node, ports) => {
+      if (node.type === 'gateway') {
+        return ports.find((port) => port.id === 'branch_out_main') ?? null;
+      }
+      return null; // 返回 null 时退回使用 portGroup
+    },
+    insertDirection: (node, port) => {
+      if (node.type === 'gateway' && port?.group === 'bottom') {
+        return 'bottom';
+      }
+      return null; // 返回 null 时按默认推导
+    },
+  }" />
+```
+
 **quick-add-panel Slot Props**
 
 | Prop                | 类型                                              | 说明                            |
 | ------------------- | ------------------------------------------------- | ------------------------------- |
 | `node`              | `FlowNodeModel`                                   | 当前触发的源节点                |
 | `api`               | `CanvasApi`                                       | 画布 API                        |
-| `insertNodeToRight` | `(node: Omit<FlowNodeModel, 'position'>) => void` | 快捷插入方法（自动连线 + 事件） |
+| `insertNodeToRight` | `(node: Omit<FlowNodeModel, 'position'>) => void` | 快捷插入方法（自动连线 + 事件）；方向遵循 `insertDirection` 配置 |
 | `closePopover`      | `() => void`                                      | 关闭弹层                        |
 
 操作触发后通过 `@ui-event` 发出对应事件：`node.quick-add`（弹层打开时）/ `node.action.quick-insert`（插入成功时）。
@@ -706,7 +790,7 @@ hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和
 ```vue
 <template>
   <CanvasLayout :editor="editor" :palette-items="paletteItems">
-    <CanvasRuntime :editor="editor" :quick-add="{ enabled: true }" @ui-event="handleUiEvent">
+    <CanvasRuntime :editor="editor" :quick-add="{ enabled: true, portGroup: 'right' }" @ui-event="handleUiEvent">
       <template #quick-add-panel="{ node, insertNodeToRight, closePopover }">
         <div class="quick-add-menu">
           <div class="quick-add-menu__title">选择节点类型</div>
@@ -1061,18 +1145,17 @@ const customItems = [
 ### 在 Schema 中注册节点组件
 
 ```typescript
+import { createBuiltinEdgeTypes } from '@blueking/flow-canvas';
 import MyTaskNode from './components/my-task-node.vue';
 import MyGatewayNode from './components/my-gateway-node.vue';
 
+const builtinEdgeTypes = createBuiltinEdgeTypes();
+
 const schema: CanvasSchema = {
   nodeTypes: {
     task: {
       component: MyTaskNode,
       getSize: () => ({ width: 180, height: 60 }),
-      getPorts: () => [
-        { id: 'left', group: 'left' },
-        { id: 'right', group: 'right' },
-      ],
       getBehavior: (node, ctx) => ({
         deletable: true,
         copyable: true,
@@ -1095,18 +1178,14 @@ const schema: CanvasSchema = {
     },
   },
   edgeTypes: {
-    default: {
-      connector: { name: 'smooth' },
-      style: (_edge, state) => ({
-        stroke: state.hovered ? '#3a84ff' : '#abb5cc',
-        strokeWidth: 2,
-      }),
-    },
+    bezier: builtinEdgeTypes.bezier,
   },
-  defaultEdgeType: 'default',
+  defaultEdgeType: 'bezier',
 };
 ```
 
+上面这个例子里，`task` 故意不写 `getPorts`，直接复用引擎默认四向端口；`gateway` 保留 `getPorts`，用于演示“当节点需要显式控制端口拓扑时再覆盖默认行为”。
+
 <br>
 
 ## CanvasApi
@@ -1132,7 +1211,7 @@ const schema: CanvasSchema = {
 | exportAsImage(options?)                         | 导出为 PNG Blob                                  |
 | exportAsSVG()                                   | 导出为 SVG 字符串                                |
 | overlay                                         | `OverlayManager` 实例，提供节点屏幕定位          |
-| insertNodeToRight(sourceNodeId, node, options?) | 在指定节点右侧插入新节点，支持自动连线和重叠检测 |
+| insertNodeToRight(sourceNodeId, node, options?) | 默认在指定节点右侧插入新节点；传 `options.direction` 后可改为上/右/下/左方向，并支持自动连线和重叠检测 |
 | getContextMenuItems(position)                   | 收集插件提供的右键菜单项                         |
 | onGraphEvent(event, handler)                    | 监听 X6 底层事件，返回取消函数                   |
 | unsafeGetGraph()                                | 获取 X6 Graph 实例（谨慎使用）                   |
@@ -1262,6 +1341,7 @@ const myPlugin: CanvasPlugin = {
 | 导出                                              | 说明                                                                              |
 | ------------------------------------------------- | --------------------------------------------------------------------------------- |
 | `createEmptyFlowModel()`                          | 创建一个空的 FlowModel（`version: '1.0'`, 空 nodes/edges）                        |
+| `createBuiltinEdgeTypes()`                        | 返回引擎内置的 `manhattan` / `bezier` 边类型定义，适合自定义 Schema 直接复用      |
 | `generateId()`                                    | 生成唯一 ID                                                                       |
 | `applyCanvasCommand(model, cmd)`                  | 纯函数 reducer，将单条命令应用到 FlowModel，返回新 FlowModel                      |
 | `createCanvasHistory(initialFlowModel, options?)` | 创建独立的历史管理器实例（通常由 `useCanvasEditor` 内部调用，高级场景可直接使用） |
@@ -1373,8 +1453,11 @@ editor.history.clear();
 | `CanvasToolbarItem`         | 工具栏项配置                                                                                                                                           |
 | `BuiltinToolbarType`        | 内置工具类型（`'undo'` / `'redo'` / `'select'` / `'auto-layout'` / `'search'` / `'minimap'` / `'export'` / `'zoom-in'` / `'zoom-out'` / `'reset'` 等） |
 | `NodeActionsConfig`         | 节点快捷操作工具栏全局配置（showDebug / showDelete / showCopy / showCopyInsert / showDisconnect / insertGap）                                          |
-| `QuickAddConfig`            | 快捷添加按钮全局配置（enabled / tooltipText）                                                                                                          |
-| `InsertNodeOptions`         | `insertNodeToRight` 选项（autoWireEdges / gap / source / label）                                                                                       |
+| `QuickAddConfig`            | 快捷添加按钮全局配置（enabled / tooltipText / portGroup / getPort）                                                                                    |
+| `QuickAddPortResolver`      | quick-add 端口选择回调类型；返回具体 port 后，优先级高于 `portGroup`                                                                                   |
+| `QuickAddInsertDirectionResolver` | quick-add 插入方向回调类型；返回具体方向后，优先级高于默认方向推导                                                                                |
+| `InsertDirection`           | 节点插入方向类型（`'top' \| 'right' \| 'bottom' \| 'left'`）                                                                                           |
+| `InsertNodeOptions`         | `insertNodeToRight` 选项（autoWireEdges / gap / source / label / direction）                                                                           |
 | `ExportOptions`             | 导出选项（backgroundColor / padding / quality）                                                                                                        |
 | `ConnectionValidator`       | 连接校验函数类型                                                                                                                                       |
 | `ConnectionValidateContext` | 连接校验上下文                                                                                                                                         |