@blueking/flow-canvas 0.0.3 → 0.0.4

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 +93 -41
  2. package/dist/index.cjs.js +1 -1
  3. package/dist/index.d.ts +53 -10
  4. package/dist/index.esm.js +2213 -1669
  5. package/dist/style.css +1 -1
  6. package/package.json +2 -5
package/README.md CHANGED
@@ -4,6 +4,12 @@
4
4
 
5
5
  `@blueking/flow-canvas` 是一个通用流程画布编辑引擎，基于 AntV X6 构建，提供数据驱动的图编辑能力。适用于 DAG / 流程图 / 工作流等场景。
6
6
 
7
+ 补充文档：
8
+
9
+ - 使用说明：[`docs/usage.md`](./docs/usage.md)
10
+ - 设计说明：[`docs/design.md`](./docs/design.md)
11
+ - 测试计划：[`docs/testing.md`](./docs/testing.md)
12
+
7
13
  ## 安装
8
14
 
9
15
  ```bash
@@ -13,7 +19,7 @@ npm install @blueking/flow-canvas
13
19
  项目中另外还需要安装以下前置依赖
14
20
 
15
21
  ```bash
16
- npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-plugin-snapline @antv/x6-plugin-dnd @antv/x6-vue-shape vue
22
+ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-plugin-snapline @antv/x6-plugin-dnd @antv/x6-vue-shape modern-screenshot vue
17
23
  ```
18
24
 
19
25
  ## 快速开始
@@ -38,6 +44,7 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
38
44
  CanvasToolbar,
39
45
  createDefaultSchema,
40
46
  createEmptyFlowModel,
47
+ searchPlugin,
41
48
  selectionPlugin,
42
49
  snaplinePlugin,
43
50
  type CanvasUiEvent,
@@ -49,7 +56,7 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
49
56
  const editor = useCanvasEditor({
50
57
  initialFlowModel: createEmptyFlowModel(),
51
58
  schema,
52
- plugins: [selectionPlugin(), snaplinePlugin()],
59
+ plugins: [selectionPlugin(), snaplinePlugin(), searchPlugin()],
53
60
  });
54
61
 
55
62
  function handleUiEvent(event: CanvasUiEvent) {
@@ -173,19 +180,21 @@ npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-
173
180
 
174
181
  #### CanvasEditorContext（返回值）
175
182
 
176
- | 属性/方法 | 类型 | 说明 |
177
- | ------------------------ | --------------------------------------------- | ------------------------------ |
178
- | flowModel | `Readonly<Ref<FlowModel>>` | 当前流程模型（响应式） |
179
- | history | `CanvasHistory` | 历史管理器 |
180
- | schema | `CanvasSchema` | Schema 定义 |
181
- | mode | `Ref<CanvasMode>` | 当前模式 |
182
- | api | `Ref<CanvasApi \| null>` | 画布 API（Runtime 挂载后可用） |
183
- | toolbarItems | `Ref<CanvasToolbarItem[]>` | 插件聚合的工具栏项 |
184
- | idGenerator | `IdGenerator` | 节点/边 ID 生成函数 |
185
- | extendedApi | `Record<string, Function>` | 插件扩展的 API |
186
- | executeCommand(envelope) | `(CommandEnvelope) => CommandExecutionResult` | 执行命令 |
187
- | replaceFlowModel(model) | `(FlowModel) => void` | 整体替换流程模型 |
188
- | setMode(mode) | `(CanvasMode) => void` | 切换模式 |
183
+ | 属性/方法 | 类型 | 说明 |
184
+ | ------------------------- | --------------------------------------------- | ------------------------------ |
185
+ | flowModel | `Readonly<Ref<FlowModel>>` | 当前流程模型（响应式） |
186
+ | history | `CanvasHistory` | 历史管理器 |
187
+ | schema | `CanvasSchema` | Schema 定义 |
188
+ | mode | `Ref<CanvasMode>` | 当前模式 |
189
+ | selectionMode | `Ref<boolean>` | 是否启用框选模式 |
190
+ | api | `Ref<CanvasApi \| null>` | 画布 API（Runtime 挂载后可用） |
191
+ | toolbarItems | `Ref<CanvasToolbarItem[]>` | 插件聚合的工具栏项 |
192
+ | idGenerator | `IdGenerator` | 节点/边 ID 生成函数 |
193
+ | extendedApi | `Record<string, Function>` | 插件扩展的 API |
194
+ | executeCommand(envelope) | `(CommandEnvelope) => CommandExecutionResult` | 执行命令 |
195
+ | replaceFlowModel(model) | `(FlowModel) => void` | 整体替换流程模型 |
196
+ | setMode(mode) | `(CanvasMode) => void` | 切换模式 |
197
+ | setSelectionMode(enabled) | `(boolean) => void` | 切换框选模式 |
189
198
 
190
199
  <br>
191
200
 
@@ -730,7 +739,6 @@ hover 节点时，指定端口会显示为"+"按钮，支持点击弹出面板
730
739
  | 属性 | 类型 | 默认 | 说明 |
731
740
  | ----------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------- |
732
741
  | `enabled` | `boolean` | `true` | 全局开关 |
733
- | `tooltipText` | `string` | `''` | 自定义 tooltip 文案（空值使用内置提示） |
734
742
  | `portGroup` | `string` | `'right'` | quick-add 默认绑定的端口分组；节点不存在该分组端口时不显示 quick-add |
735
743
  | `getPort` | `function` | - | 精确指定当前节点使用哪个 port；优先级高于 `portGroup` |
736
744
  | `insertDirection` | `string \| function` | - | 点击 quick-add 插入节点时使用的方向；默认跟随当前绑定 port 的标准方向，不可推断时回退为 `'right'` |
@@ -1012,7 +1020,7 @@ interface NodePaletteItem {
1012
1020
 
1013
1021
  ### CanvasToolbar
1014
1022
 
1015
- 可选的工具栏组件。默认浮动在画布左上角，包含搜索、下载、缩放、重置等操作。
1023
+ 可选的工具栏组件。默认浮动在画布左上角，内置下载、缩放、重置等核心操作；`search` / `minimap` 由对应插件注入后显示。
1016
1024
 
1017
1025
  | Prop | 类型 | 默认 | 说明 |
1018
1026
  | ------- | ---------------------- | ---------- | --------------------------------------- |
@@ -1035,9 +1043,9 @@ const items = createDefaultToolbarItems();
1035
1043
  // 恢复显示撤销/重做
1036
1044
  const itemsWithHistory = createDefaultToolbarItems({ include: ['undo', 'redo'] });
1037
1045
 
1038
- // 恢复撤销/重做，同时排除搜索，追加自定义项
1046
+ // 恢复撤销/重做，追加自定义项
1039
1047
  const customItems = [
1040
- ...createDefaultToolbarItems({ include: ['undo', 'redo'], exclude: ['search'] }),
1048
+ ...createDefaultToolbarItems({ include: ['undo', 'redo'] }),
1041
1049
  { id: 'my-tool', type: 'custom', icon: 'my-icon-class', onClick: handleClick },
1042
1050
  ];
1043
1051
  ```
@@ -1208,15 +1216,16 @@ const schema: CanvasSchema = {
1208
1216
  | centerContent() | 居中画布内容 |
1209
1217
  | scrollToNode(nodeId) | 滚动到指定节点 |
1210
1218
  | getSelection() | 获取当前选区 `{ nodeIds, edgeIds }` |
1219
+ | getSelectionBounds(selection?) | 获取当前选区或指定选区的整体包围盒，用于挂载选区工具条等 overlay |
1211
1220
  | selectNodes(ids) | 选中指定节点 |
1212
1221
  | selectEdges(ids) | 选中指定边 |
1213
1222
  | clearSelection() | 清除选区 |
1223
+ | deleteSelection(options?) | 统一删除当前选区或指定选区；按 schema behavior 过滤不可删元素，默认成功后清空选区 |
1214
1224
  | registerDndSource(el, factory) | 注册 DND 拖拽源，返回清理函数 |
1215
1225
  | startConnection(nodeId, portId?) | 从指定节点/端口发起连线 |
1216
1226
  | highlightNodes(ids) / highlightEdges(ids) | 高亮指定元素 |
1217
1227
  | clearHighlight() | 清除所有高亮 |
1218
- | exportAsImage(options?) | 导出为 PNG Blob |
1219
- | exportAsSVG() | 导出为 SVG 字符串 |
1228
+ | exportAsImage(options?) | 导出为 PNG Blob（基于 `modern-screenshot`，需安装为 peer dependency） |
1220
1229
  | overlay | `OverlayManager` 实例，提供节点屏幕定位 |
1221
1230
  | insertNodeToRight(sourceNodeId, node, options?) | 默认在指定节点右侧插入新节点；传 `options.direction` 后可改为上/右/下/左方向，并支持自动连线和重叠检测 |
1222
1231
  | getContextMenuItems(position) | 收集插件提供的右键菜单项 |
@@ -1227,9 +1236,25 @@ const schema: CanvasSchema = {
1227
1236
 
1228
1237
  ## 内置插件
1229
1238
 
1239
+ ### 框选模式
1240
+
1241
+ `selectionMode` 只表示“是否启用框选模式”，不等价于“是否允许节点被选中”。
1242
+
1243
+ - `selectionMode = true`
1244
+ 空白区域左键拖拽启用 rubberband 框选。
1245
+ - `selectionMode = false`
1246
+ 空白区域左键拖拽恢复为画布平移。
1247
+ - 无论 `selectionMode` 是否开启
1248
+ 普通点击选中、`selectNodes()`、`selectEdges()` 仍然可用。
1249
+
1250
+ ```typescript
1251
+ editor.setSelectionMode(true);
1252
+ editor.setSelectionMode(false);
1253
+ ```
1254
+
1230
1255
  ### selectionPlugin(options?)
1231
1256
 
1232
- 启用节点/边的框选和多选能力。
1257
+ 接入 X6 的通用选区能力，支持多选、框选和 `_selectable` 节点过滤。
1233
1258
 
1234
1259
  ```typescript
1235
1260
  selectionPlugin({
@@ -1239,6 +1264,12 @@ selectionPlugin({
1239
1264
  });
1240
1265
  ```
1241
1266
 
1267
+ 注意：
1268
+
1269
+ - `selectionPlugin()` 负责注册 X6 Selection 能力。
1270
+ - `selectionMode` 由 `CanvasRuntime` 在运行时控制 rubberband / panning 的切换。
1271
+ - `selectionPlugin()` 本身不负责决定当前是否处于框选模式。
1272
+
1242
1273
  ### snaplinePlugin(options?)
1243
1274
 
1244
1275
  节点拖拽时显示对齐辅助线。
@@ -1263,6 +1294,24 @@ connectionValidatorPlugin((ctx) => {
1263
1294
  });
1264
1295
  ```
1265
1296
 
1297
+ ### searchPlugin(options?)
1298
+
1299
+ 工具栏搜索节点。点击搜索图标后弹出面板，支持按关键字过滤节点并通过 `Enter` / 点击快速定位到目标节点。
1300
+
1301
+ ```typescript
1302
+ searchPlugin({
1303
+ placeholder: '搜索节点名称',
1304
+ getNodeMeta(node) {
1305
+ const stageName = typeof node.payload?.stageName === 'string' ? node.payload.stageName : '';
1306
+ return {
1307
+ label: node.label ?? '',
1308
+ subtitle: stageName || undefined,
1309
+ keywords: [node.label ?? '', stageName],
1310
+ };
1311
+ },
1312
+ });
1313
+ ```
1314
+
1266
1315
  ### minimapPlugin(options?)
1267
1316
 
1268
1317
  小地图。传入 `container` 后启用。
@@ -1379,23 +1428,24 @@ editor.history.clear();
1379
1428
 
1380
1429
  ## 事件类型 (CanvasUiEvent)
1381
1430
 
1382
- | type | 附加字段 | 说明 |
1383
- | ------------------------ | ----------------------- | ---------------- |
1384
- | node.click | nodeId | 节点点击 |
1385
- | node.dblclick | nodeId | 节点双击 |
1386
- | node.contextmenu | nodeId, position | 节点右键 |
1387
- | edge.click | edgeId | 边点击 |
1388
- | edge.label.click | edgeId, labelId | 边标签点击 |
1389
- | blank.click | position | 空白区域点击 |
1390
- | blank.contextmenu | position | 空白区域右键 |
1391
- | selection.change | nodeIds, edgeIds | 选区变更 |
1392
- | node.action.delete | nodeId | 快捷删除节点 |
1393
- | node.action.copy | sourceNodeId, newNodeId | 快捷复制节点 |
1394
- | node.action.copy-insert | sourceNodeId, newNodeId | 快捷复制并插入 |
1395
- | node.action.disconnect | nodeId, edgeIds | 快捷断开连线 |
1396
- | node.action.debug | nodeId | 快捷调试 |
1397
- | node.quick-add | nodeId, position | 快捷添加弹层打开 |
1398
- | node.action.quick-insert | sourceNodeId, newNodeId | 快捷插入节点 |
1431
+ | type | 附加字段 | 说明 |
1432
+ | ------------------------ | ----------------------- | ---------------------- |
1433
+ | node.click | nodeId | 节点点击 |
1434
+ | node.dblclick | nodeId | 节点双击 |
1435
+ | node.contextmenu | nodeId, position | 节点右键 |
1436
+ | edge.click | edgeId | 边点击 |
1437
+ | edge.label.click | edgeId, labelId | 边标签点击 |
1438
+ | blank.click | position | 空白区域点击 |
1439
+ | blank.contextmenu | position | 空白区域右键 |
1440
+ | selection.change | nodeIds, edgeIds | 选区变更 |
1441
+ | node.action.delete | nodeId | 快捷删除节点 |
1442
+ | node.action.copy | sourceNodeId, newNodeId | 快捷复制节点 |
1443
+ | node.action.copy-insert | sourceNodeId, newNodeId | 快捷复制并插入 |
1444
+ | node.action.disconnect | nodeId, edgeIds | 快捷断开连线 |
1445
+ | node.action.debug | nodeId | 快捷调试 |
1446
+ | node.quick-add | nodeId, position | 快捷添加弹层打开 |
1447
+ | node.action.quick-insert | sourceNodeId, newNodeId | 快捷插入节点 |
1448
+ | toolbar.auto-layout | — | 自动排版（由外层实现） |
1399
1449
 
1400
1450
  <br>
1401
1451
 
@@ -1461,12 +1511,13 @@ editor.history.clear();
1461
1511
  | `CanvasToolbarItem` | 工具栏项配置 |
1462
1512
  | `BuiltinToolbarType` | 内置工具类型（`'undo'` / `'redo'` / `'select'` / `'auto-layout'` / `'search'` / `'minimap'` / `'export'` / `'zoom-in'` / `'zoom-out'` / `'reset'` 等） |
1463
1513
  | `NodeActionsConfig` | 节点快捷操作工具栏全局配置（showDebug / showDelete / showCopy / showCopyInsert / showDisconnect / insertGap） |
1464
- | `QuickAddConfig` | 快捷添加按钮全局配置（enabled / tooltipText / portGroup / getPort） |
1514
+ | `QuickAddConfig` | 快捷添加按钮全局配置（enabled / portGroup / getPort / insertDirection） |
1465
1515
  | `QuickAddPortResolver` | quick-add 端口选择回调类型；返回具体 port 后，优先级高于 `portGroup` |
1466
1516
  | `QuickAddInsertDirectionResolver` | quick-add 插入方向回调类型；返回具体方向后，优先级高于默认方向推导 |
1467
1517
  | `InsertDirection` | 节点插入方向类型（`'top' \| 'right' \| 'bottom' \| 'left'`） |
1468
1518
  | `InsertNodeOptions` | `insertNodeToRight` 选项（autoWireEdges / gap / source / label / direction） |
1469
- | `ExportOptions` | 导出选项（backgroundColor / padding / quality） |
1519
+ | `ExportOptions` | 导出选项（backgroundColor / padding / quality / scale） |
1520
+ | `DeleteSelectionOptions` | `deleteSelection` 选项（selection / source / label / clearSelectionAfterApply） |
1470
1521
  | `ConnectionValidator` | 连接校验函数类型 |
1471
1522
  | `ConnectionValidateContext` | 连接校验上下文 |
1472
1523
  | `ConnectionValidateResult` | 连接校验结果 |
@@ -1502,4 +1553,5 @@ editor.history.clear();
1502
1553
  | ------------------------ | -------------------- |
1503
1554
  | `SelectionPluginOptions` | selectionPlugin 配置 |
1504
1555
  | `SnaplinePluginOptions` | snaplinePlugin 配置 |
1556
+ | `SearchPluginOptions` | searchPlugin 配置 |
1505
1557
  | `MinimapPluginOptions` | minimapPlugin 配置 |