@blueking/flow-canvas 0.0.2 → 0.0.3

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 (6) hide show
  1. package/README.md +96 -88
  2. package/dist/index.cjs.js +1 -1
  3. package/dist/index.d.ts +16 -3
  4. package/dist/index.esm.js +1273 -1180
  5. package/dist/style.css +1 -1
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -167,6 +167,7 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
167
167
  | plugins | `CanvasPlugin[]` | 否 | `[]` | 插件列表 |
168
168
  | mode | `CanvasMode` | 否 | `'edit'` | `'edit'` / `'readonly'` / `'thumbnail'` |
169
169
  | historyOptions | `CanvasHistoryOptions` | 否 | - | 历史配置 |
170
+ | idGenerator | `IdGenerator` | 否 | 内置生成 | 自定义节点/边 ID 生成函数 |
170
171
  | onCommandResult | `(result) => void` | 否 | - | 命令执行结果回调 |
171
172
  | onFlowModelChange | `(event) => void` | 否 | - | FlowModel 变更回调 |
172
173
 
@@ -180,6 +181,7 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
180
181
  | mode | `Ref<CanvasMode>` | 当前模式 |
181
182
  | api | `Ref<CanvasApi \| null>` | 画布 API（Runtime 挂载后可用） |
182
183
  | toolbarItems | `Ref<CanvasToolbarItem[]>` | 插件聚合的工具栏项 |
184
+ | idGenerator | `IdGenerator` | 节点/边 ID 生成函数 |
183
185
  | extendedApi | `Record<string, Function>` | 插件扩展的 API |
184
186
  | executeCommand(envelope) | `(CommandEnvelope) => CommandExecutionResult` | 执行命令 |
185
187
  | replaceFlowModel(model) | `(FlowModel) => void` | 整体替换流程模型 |
@@ -649,19 +651,20 @@ if (result.status === 'applied') {
649
651
 
650
652
  核心渲染组件，负责创建 X6 Graph 并双向桥接 FlowModel。
651
653
 
652
- | Prop | 类型 | 说明 |
653
- | ------------ | ------------------------- | ------------------------------------------ |
654
- | editor | `CanvasEditorContext` | 编辑器实例（必填） |
655
- | graphOptions | `Record<string, unknown>` | 额外 X6 Graph 选项 |
656
- | nodeActions | `NodeActionsConfig` | 节点快捷操作工具栏配置（见下方详细说明） |
657
- | quickAdd | `QuickAddConfig` | 快捷添加按钮配置（默认绑定右侧端口，见下方详细说明） |
654
+ | Prop | 类型 | 说明 |
655
+ | ---------------------------- | -------------------------------------------- | ---------------------------------------------------- |
656
+ | editor | `CanvasEditorContext` | 编辑器实例（必填） |
657
+ | graphOptions | `Record<string, unknown>` | 额外 X6 Graph 选项 |
658
+ | nodeActions | `NodeActionsConfig` | 节点快捷操作工具栏配置（见下方详细说明） |
659
+ | quickAdd | `QuickAddConfig` | 快捷添加按钮配置（默认绑定右侧端口，见下方详细说明） |
660
+ | getConnectionExcludedNodeIds | `(sourceNodeId: string) => Iterable<string>` | 拖拽连线时返回不应显示端口的节点 ID 集合 |
658
661
 
659
662
  | Emit | 参数 | 说明 |
660
663
  | -------- | --------------- | -------------------- |
661
664
  | ui-event | `CanvasUiEvent` | 非命令类 UI 交互事件 |
662
665
 
663
- | Slot | Props | 说明 |
664
- | --------------- | ------------------------------------------------ | ----------------------------------------------------------- |
666
+ | Slot | Props | 说明 |
667
+ | --------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
665
668
  | quick-add-panel | `{ node, api, insertNodeToRight, closePopover }` | 快捷添加弹层内容，点击绑定端口上的"+"按钮时显示（默认显示提示文字） |
666
669
 
667
670
  #### 节点快捷操作工具栏
@@ -687,19 +690,23 @@ if (result.status === 'applied') {
687
690
 
688
691
  通过 schema `getBehavior` 返回值控制每个节点类型的工具栏行为：
689
692
 
690
- | 属性 | 说明 |
691
- | -------------------- | --------------------------------------------------------------------------------- |
692
- | `showActions` | `false` → 该节点类型不显示整个工具栏 |
693
- | `deletable` | `false` → 隐藏删除按钮 |
694
- | `copyable` | `false` → 隐藏复制和复制并插入按钮 |
695
- | `disconnectable` | `false` → 隐藏断开连线按钮 |
696
- | `debuggable` | `false` → 隐藏调试按钮（需全局 `showDebug` 也为 `true`） |
697
- | `deleteDisabled` | `true` → 删除按钮可见但置灰不可点击 |
698
- | `copyDisabled` | `true` → 复制按钮置灰 |
699
- | `copyInsertDisabled` | `true` → 复制并插入按钮置灰 |
700
- | `disconnectDisabled` | `true` → 断开连线按钮置灰 |
701
- | `debugDisabled` | `true` → 调试按钮置灰 |
702
- | `actionsOffset` | `{ x?: number; y?: number }` — 工具栏位置偏移（px），相对于默认位置（节点右下角） |
693
+ | 属性 | 说明 |
694
+ | --------------------- | --------------------------------------------------------------------------------- |
695
+ | `showActions` | `false` → 该节点类型不显示整个工具栏 |
696
+ | `deletable` | `false` → 隐藏删除按钮 |
697
+ | `copyable` | `false` → 隐藏复制和复制并插入按钮 |
698
+ | `disconnectable` | `false` → 隐藏断开连线按钮 |
699
+ | `debuggable` | `false` → 隐藏调试按钮（需全局 `showDebug` 也为 `true`） |
700
+ | `deleteDisabled` | `true` → 删除按钮可见但置灰不可点击 |
701
+ | `copyDisabled` | `true` → 复制按钮置灰 |
702
+ | `copyInsertDisabled` | `true` → 复制并插入按钮置灰 |
703
+ | `disconnectDisabled` | `true` → 断开连线按钮置灰 |
704
+ | `debugDisabled` | `true` → 调试按钮置灰 |
705
+ | `connectable` | `false` → 此节点端口不允许发起连线（控制 magnet 属性） |
706
+ | `targetable` | `false` → 拖拽连线期间不显示此节点端口（不可作为连线目标） |
707
+ | `bringToFrontOnDrag` | `false` → 拖拽时不临时置顶节点 z-index（默认 `true`） |
708
+ | `hidePortForQuickAdd` | `false` → quick-add 激活时不隐藏对应方向的连接端口（默认 `true`） |
709
+ | `actionsOffset` | `{ x?: number; y?: number }` — 工具栏位置偏移（px），相对于默认位置（节点右下角） |
703
710
 
704
711
  按钮有效可见性 = 全局 `show*` AND 逐节点 `*able !== false`；
705
712
  按钮禁用状态 = 逐节点 `*Disabled === true`。
@@ -720,13 +727,13 @@ hover 节点时，指定端口会显示为"+"按钮，支持点击弹出面板
720
727
 
721
728
  **QuickAddConfig（全局配置）**
722
729
 
723
- | 属性 | 类型 | 默认 | 说明 |
724
- | ------------- | --------- | --------- | -------------------------------------------------------------- |
725
- | `enabled` | `boolean` | `true` | 全局开关 |
726
- | `tooltipText` | `string` | `''` | 自定义 tooltip 文案（空值使用内置提示） |
727
- | `portGroup` | `string` | `'right'` | quick-add 默认绑定的端口分组；节点不存在该分组端口时不显示 quick-add |
728
- | `getPort` | `function` | - | 精确指定当前节点使用哪个 port；优先级高于 `portGroup` |
729
- | `insertDirection` | `string \| function` | - | 点击 quick-add 插入节点时使用的方向；默认跟随当前绑定 port 的标准方向，不可推断时回退为 `'right'` |
730
+ | 属性 | 类型 | 默认 | 说明 |
731
+ | ----------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------- |
732
+ | `enabled` | `boolean` | `true` | 全局开关 |
733
+ | `tooltipText` | `string` | `''` | 自定义 tooltip 文案（空值使用内置提示） |
734
+ | `portGroup` | `string` | `'right'` | quick-add 默认绑定的端口分组；节点不存在该分组端口时不显示 quick-add |
735
+ | `getPort` | `function` | - | 精确指定当前节点使用哪个 port；优先级高于 `portGroup` |
736
+ | `insertDirection` | `string \| function` | - | 点击 quick-add 插入节点时使用的方向；默认跟随当前绑定 port 的标准方向，不可推断时回退为 `'right'` |
730
737
 
731
738
  **NodeBehaviorConfig 中的快捷添加相关字段（逐节点控制）**
732
739
 
@@ -776,12 +783,12 @@ slot 中提供的 `insertNodeToRight` helper 出于兼容仍保留这个名字
776
783
 
777
784
  **quick-add-panel Slot Props**
778
785
 
779
- | Prop | 类型 | 说明 |
780
- | ------------------- | ------------------------------------------------- | ------------------------------- |
781
- | `node` | `FlowNodeModel` | 当前触发的源节点 |
782
- | `api` | `CanvasApi` | 画布 API |
786
+ | Prop | 类型 | 说明 |
787
+ | ------------------- | ------------------------------------------------- | ---------------------------------------------------------------- |
788
+ | `node` | `FlowNodeModel` | 当前触发的源节点 |
789
+ | `api` | `CanvasApi` | 画布 API |
783
790
  | `insertNodeToRight` | `(node: Omit<FlowNodeModel, 'position'>) => void` | 快捷插入方法（自动连线 + 事件）；方向遵循 `insertDirection` 配置 |
784
- | `closePopover` | `() => void` | 关闭弹层 |
791
+ | `closePopover` | `() => void` | 关闭弹层 |
785
792
 
786
793
  操作触发后通过 `@ui-event` 发出对应事件：`node.quick-add`（弹层打开时）/ `node.action.quick-insert`（插入成功时）。
787
794
 
@@ -1073,13 +1080,13 @@ const customItems = [
1073
1080
  </template>
1074
1081
 
1075
1082
  <style scoped>
1076
- .my-canvas-wrapper {
1077
- --flow-canvas-toolbar-top: auto;
1078
- --flow-canvas-toolbar-bottom: 16px;
1079
- --flow-canvas-toolbar-left: 50%;
1080
- --flow-canvas-toolbar-right: auto;
1081
- --flow-canvas-toolbar-bg: #1a1a2e;
1082
- }
1083
+ .my-canvas-wrapper {
1084
+ --flow-canvas-toolbar-top: auto;
1085
+ --flow-canvas-toolbar-bottom: 16px;
1086
+ --flow-canvas-toolbar-left: 50%;
1087
+ --flow-canvas-toolbar-right: auto;
1088
+ --flow-canvas-toolbar-bg: #1a1a2e;
1089
+ }
1083
1090
  </style>
1084
1091
  ```
1085
1092
 
@@ -1192,29 +1199,29 @@ const schema: CanvasSchema = {
1192
1199
 
1193
1200
  `editor.api.value` 在 `CanvasRuntime` 挂载后可用，之前为 `null`。
1194
1201
 
1195
- | 方法 | 说明 |
1196
- | ----------------------------------------------- | ------------------------------------------------ |
1197
- | zoomIn() / zoomOut() | 缩放 |
1198
- | zoomTo(value) | 缩放到指定比例 |
1199
- | zoomToFit() | 自适应画布 |
1200
- | getZoom() | 获取当前缩放比例 |
1201
- | centerContent() | 居中画布内容 |
1202
- | scrollToNode(nodeId) | 滚动到指定节点 |
1203
- | getSelection() | 获取当前选区 `{ nodeIds, edgeIds }` |
1204
- | selectNodes(ids) | 选中指定节点 |
1205
- | selectEdges(ids) | 选中指定边 |
1206
- | clearSelection() | 清除选区 |
1207
- | registerDndSource(el, factory) | 注册 DND 拖拽源，返回清理函数 |
1208
- | startConnection(nodeId, portId?) | 从指定节点/端口发起连线 |
1209
- | highlightNodes(ids) / highlightEdges(ids) | 高亮指定元素 |
1210
- | clearHighlight() | 清除所有高亮 |
1211
- | exportAsImage(options?) | 导出为 PNG Blob |
1212
- | exportAsSVG() | 导出为 SVG 字符串 |
1213
- | overlay | `OverlayManager` 实例，提供节点屏幕定位 |
1202
+ | 方法 | 说明 |
1203
+ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
1204
+ | zoomIn() / zoomOut() | 缩放 |
1205
+ | zoomTo(value) | 缩放到指定比例 |
1206
+ | zoomToFit() | 自适应画布 |
1207
+ | getZoom() | 获取当前缩放比例 |
1208
+ | centerContent() | 居中画布内容 |
1209
+ | scrollToNode(nodeId) | 滚动到指定节点 |
1210
+ | getSelection() | 获取当前选区 `{ nodeIds, edgeIds }` |
1211
+ | selectNodes(ids) | 选中指定节点 |
1212
+ | selectEdges(ids) | 选中指定边 |
1213
+ | clearSelection() | 清除选区 |
1214
+ | registerDndSource(el, factory) | 注册 DND 拖拽源，返回清理函数 |
1215
+ | startConnection(nodeId, portId?) | 从指定节点/端口发起连线 |
1216
+ | highlightNodes(ids) / highlightEdges(ids) | 高亮指定元素 |
1217
+ | clearHighlight() | 清除所有高亮 |
1218
+ | exportAsImage(options?) | 导出为 PNG Blob |
1219
+ | exportAsSVG() | 导出为 SVG 字符串 |
1220
+ | overlay | `OverlayManager` 实例，提供节点屏幕定位 |
1214
1221
  | insertNodeToRight(sourceNodeId, node, options?) | 默认在指定节点右侧插入新节点；传 `options.direction` 后可改为上/右/下/左方向，并支持自动连线和重叠检测 |
1215
- | getContextMenuItems(position) | 收集插件提供的右键菜单项 |
1216
- | onGraphEvent(event, handler) | 监听 X6 底层事件，返回取消函数 |
1217
- | unsafeGetGraph() | 获取 X6 Graph 实例（谨慎使用） |
1222
+ | getContextMenuItems(position) | 收集插件提供的右键菜单项 |
1223
+ | onGraphEvent(event, handler) | 监听 X6 底层事件，返回取消函数 |
1224
+ | unsafeGetGraph() | 获取 X6 Graph 实例（谨慎使用） |
1218
1225
 
1219
1226
  <br>
1220
1227
 
@@ -1345,6 +1352,7 @@ const myPlugin: CanvasPlugin = {
1345
1352
  | `generateId()` | 生成唯一 ID |
1346
1353
  | `applyCanvasCommand(model, cmd)` | 纯函数 reducer，将单条命令应用到 FlowModel，返回新 FlowModel |
1347
1354
  | `createCanvasHistory(initialFlowModel, options?)` | 创建独立的历史管理器实例（通常由 `useCanvasEditor` 内部调用，高级场景可直接使用） |
1355
+ | `IdGenerator` | `(type: 'node' \| 'edge') => string`，自定义 ID 生成函数类型 |
1348
1356
  | `CanvasConstraintError` | 命令违反 FlowModel 不变量时抛出的错误类（如重复 ID、悬挂引用等） |
1349
1357
  | `CanvasSchemaError` | 未知节点/边类型等 Schema 级错误类 |
1350
1358
 
@@ -1407,16 +1415,16 @@ editor.history.clear();
1407
1415
 
1408
1416
  ### Schema 与渲染
1409
1417
 
1410
- | 类型 | 说明 |
1411
- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1412
- | `CanvasSchema` | 画布配置（nodeTypes / edgeTypes） |
1413
- | `CanvasNodeDefinition` | 节点类型定义（component / getSize / getPorts / getBehavior） |
1414
- | `CanvasEdgeDefinition` | 边类型定义（router / connector / style / labelDraggable）。`labelRenderer` 字段为 `@experimental`，当前未实现 |
1415
- | `CanvasCallbackContext` | 运行时上下文（api / flowModel / history / mode） |
1416
- | `CanvasMode` | 模式：`'edit'` / `'readonly'` / `'thumbnail'` |
1417
- | `NodeBehaviorConfig` | 节点行为配置（showActions / draggable / selectable / deletable / connectable / copyable / disconnectable / debuggable / quickAddEnabled + 各按钮 Disabled 状态） |
1418
- | `EdgeRenderState` | 边渲染状态（selected / highlighted / hovered） |
1419
- | `EdgeStyle` | 边样式（stroke / strokeWidth / strokeDasharray） |
1418
+ | 类型 | 说明 |
1419
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1420
+ | `CanvasSchema` | 画布配置（nodeTypes / edgeTypes） |
1421
+ | `CanvasNodeDefinition` | 节点类型定义（component / getSize / getPorts / getBehavior） |
1422
+ | `CanvasEdgeDefinition` | 边类型定义（router / connector / style / labelDraggable）。`labelRenderer` 字段为 `@experimental`，当前未实现 |
1423
+ | `CanvasCallbackContext` | 运行时上下文（api / flowModel / history / mode） |
1424
+ | `CanvasMode` | 模式：`'edit'` / `'readonly'` / `'thumbnail'` |
1425
+ | `NodeBehaviorConfig` | 节点行为配置（showActions / draggable / selectable / deletable / connectable / targetable / copyable / disconnectable / debuggable / quickAddEnabled / bringToFrontOnDrag / hidePortForQuickAdd + 各按钮 Disabled 状态） |
1426
+ | `EdgeRenderState` | 边渲染状态（selected / highlighted / hovered） |
1427
+ | `EdgeStyle` | 边样式（stroke / strokeWidth / strokeDasharray） |
1420
1428
 
1421
1429
  ### 命令系统
1422
1430
 
@@ -1447,22 +1455,22 @@ editor.history.clear();
1447
1455
 
1448
1456
  ### API 与工具栏
1449
1457
 
1450
- | 类型 | 说明 |
1451
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
1452
- | `CanvasApi` | 画布公共 API 接口（含 `insertNodeToRight`） |
1453
- | `CanvasToolbarItem` | 工具栏项配置 |
1454
- | `BuiltinToolbarType` | 内置工具类型（`'undo'` / `'redo'` / `'select'` / `'auto-layout'` / `'search'` / `'minimap'` / `'export'` / `'zoom-in'` / `'zoom-out'` / `'reset'` 等） |
1455
- | `NodeActionsConfig` | 节点快捷操作工具栏全局配置（showDebug / showDelete / showCopy / showCopyInsert / showDisconnect / insertGap） |
1456
- | `QuickAddConfig` | 快捷添加按钮全局配置（enabled / tooltipText / portGroup / getPort） |
1457
- | `QuickAddPortResolver` | quick-add 端口选择回调类型；返回具体 port 后，优先级高于 `portGroup` |
1458
- | `QuickAddInsertDirectionResolver` | quick-add 插入方向回调类型；返回具体方向后，优先级高于默认方向推导 |
1459
- | `InsertDirection` | 节点插入方向类型（`'top' \| 'right' \| 'bottom' \| 'left'`） |
1460
- | `InsertNodeOptions` | `insertNodeToRight` 选项（autoWireEdges / gap / source / label / direction） |
1461
- | `ExportOptions` | 导出选项（backgroundColor / padding / quality） |
1462
- | `ConnectionValidator` | 连接校验函数类型 |
1463
- | `ConnectionValidateContext` | 连接校验上下文 |
1464
- | `ConnectionValidateResult` | 连接校验结果 |
1465
- | `NodePaletteItem` | 节点面板项（type / label / icon） |
1458
+ | 类型 | 说明 |
1459
+ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
1460
+ | `CanvasApi` | 画布公共 API 接口（含 `insertNodeToRight`） |
1461
+ | `CanvasToolbarItem` | 工具栏项配置 |
1462
+ | `BuiltinToolbarType` | 内置工具类型（`'undo'` / `'redo'` / `'select'` / `'auto-layout'` / `'search'` / `'minimap'` / `'export'` / `'zoom-in'` / `'zoom-out'` / `'reset'` 等） |
1463
+ | `NodeActionsConfig` | 节点快捷操作工具栏全局配置（showDebug / showDelete / showCopy / showCopyInsert / showDisconnect / insertGap） |
1464
+ | `QuickAddConfig` | 快捷添加按钮全局配置（enabled / tooltipText / portGroup / getPort） |
1465
+ | `QuickAddPortResolver` | quick-add 端口选择回调类型；返回具体 port 后，优先级高于 `portGroup` |
1466
+ | `QuickAddInsertDirectionResolver` | quick-add 插入方向回调类型；返回具体方向后，优先级高于默认方向推导 |
1467
+ | `InsertDirection` | 节点插入方向类型（`'top' \| 'right' \| 'bottom' \| 'left'`） |
1468
+ | `InsertNodeOptions` | `insertNodeToRight` 选项（autoWireEdges / gap / source / label / direction） |
1469
+ | `ExportOptions` | 导出选项（backgroundColor / padding / quality） |
1470
+ | `ConnectionValidator` | 连接校验函数类型 |
1471
+ | `ConnectionValidateContext` | 连接校验上下文 |
1472
+ | `ConnectionValidateResult` | 连接校验结果 |
1473
+ | `NodePaletteItem` | 节点面板项（type / label / icon） |
1466
1474
 
1467
1475
  ### 默认 Schema
1468
1476