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

package/README.md

@@ -10,16 +10,10 @@
 npm install @blueking/flow-canvas
 ```
 
-### 必需的对等依赖
+项目中另外还需要安装以下前置依赖
 
 ```bash
-npm install @antv/x6 @antv/x6-plugin-minimap @antv/x6-plugin-selection @antv/x6-plugin-snapline @antv/x6-vue-shape vue
-```
-
-### 可选依赖
-
-```bash
-npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
+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
 ```
 
 ## 快速开始
@@ -158,7 +152,7 @@ npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
 </script>
 ```
 
----
+<br>
 
 ## 核心 API
 
@@ -193,7 +187,7 @@ npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
 | replaceFlowModel(model)  | `(FlowModel) => void`                         | 整体替换流程模型               |
 | setMode(mode)            | `(CanvasMode) => void`                        | 切换模式                       |
 
----
+<br>
 
 ## FlowModel 数据结构
 
@@ -227,7 +221,7 @@ interface FlowEdgeModel {
 }
 ```
 
----
+<br>
 
 ## CanvasSchema 配置
 
@@ -264,7 +258,7 @@ interface CanvasEdgeDefinition {
 
 > **注意：** `labelRenderer` 字段在类型定义中存在但标记为 `@experimental`，当前版本尚未完整实现。如需自定义边标签样式，建议通过 `x6EdgeConfig.defaultLabel` 配置 X6 原生标签 markup。
 
----
+<br>
 
 ## createDefaultSchema — 开箱即用的 Schema 工厂
 
@@ -278,11 +272,11 @@ const { schema, paletteItems } = createDefaultSchema(options?);
 
 ### DefaultSchemaOptions
 
-| 参数            | 类型                                      | 默认          | 说明                                          |
-| --------------- | ----------------------------------------- | ------------- | --------------------------------------------- |
-| nodeTypes       | `Record<string, DefaultNodeTypeConfig>`   | 7 种内置类型  | 自定义节点类型列表，传入后替换内置类型         |
-| defaultEdgeType | `string`                                  | `'manhattan'` | 默认连线类型，内置 `'manhattan'` 和 `'bezier'` |
-| edgeTypes       | `Record<string, CanvasEdgeDefinition>`    | -             | 额外/覆盖的边类型定义，会与内置类型合并        |
+| 参数            | 类型                                    | 默认          | 说明                                           |
+| --------------- | --------------------------------------- | ------------- | ---------------------------------------------- |
+| nodeTypes       | `Record<string, DefaultNodeTypeConfig>` | 7 种内置类型  | 自定义节点类型列表，传入后替换内置类型         |
+| defaultEdgeType | `string`                                | `'manhattan'` | 默认连线类型，内置 `'manhattan'` 和 `'bezier'` |
+| edgeTypes       | `Record<string, CanvasEdgeDefinition>`  | -             | 额外/覆盖的边类型定义，会与内置类型合并        |
 
 ### 返回值
 
@@ -295,15 +289,15 @@ const { schema, paletteItems } = createDefaultSchema(options?);
 
 不传 `nodeTypes` 参数时，默认包含 7 种节点：
 
-| 类型                         | 标签         | 尺寸      |
-| ---------------------------- | ------------ | --------- |
-| `start`                      | 开始         | 88 × 40   |
-| `end`                        | 结束         | 88 × 40   |
-| `empty`                      | 空节点       | 240 × 48  |
-| `parallel-gateway`           | 并行网关     | 64 × 64   |
-| `branch-gateway`             | 分支网关     | 64 × 64   |
-| `converge-gateway`           | 汇聚网关     | 64 × 64   |
-| `conditional-parallel-gateway` | 条件并行网关 | 64 × 64   |
+| 类型                           | 标签         | 尺寸     |
+| ------------------------------ | ------------ | -------- |
+| `start`                        | 开始         | 88 × 40  |
+| `end`                          | 结束         | 88 × 40  |
+| `empty`                        | 空节点       | 240 × 48 |
+| `parallel-gateway`             | 并行网关     | 64 × 64  |
+| `branch-gateway`               | 分支网关     | 64 × 64  |
+| `converge-gateway`             | 汇聚网关     | 64 × 64  |
+| `conditional-parallel-gateway` | 条件并行网关 | 64 × 64  |
 
 每种节点均使用内置 `DefaultNode` 组件渲染，自带上/右/下/左四个连接端口。
 
@@ -323,10 +317,10 @@ const { schema, paletteItems } = createDefaultSchema({
 
 `createDefaultSchema` 内置两种连线类型：
 
-| 类型                    | 路由        | 连接器                 | 说明                 |
-| ----------------------- | ----------- | ---------------------- | -------------------- |
-| `manhattan`（默认）     | `manhattan` | `rounded`（radius: 8）| 直角折线，圆角转弯   |
-| `bezier`                | 无          | `smooth`               | 贝塞尔曲线，平滑 S 形 |
+| 类型                | 路由        | 连接器                 | 说明                  |
+| ------------------- | ----------- | ---------------------- | --------------------- |
+| `manhattan`（默认） | `manhattan` | `rounded`（radius: 8） | 直角折线，圆角转弯    |
+| `bezier`            | 无          | `smooth`               | 贝塞尔曲线，平滑 S 形 |
 
 **切换为贝塞尔曲线连线：**
 
@@ -359,7 +353,9 @@ const { schema, paletteItems } = createDefaultSchema({
 
 ```typescript
 const schema: CanvasSchema = {
-  nodeTypes: { /* ... */ },
+  nodeTypes: {
+    /* ... */
+  },
   edgeTypes: {
     bezier: {
       connector: { name: 'smooth' },
@@ -396,27 +392,188 @@ const schema: CanvasSchema = {
 - **连线**：宽度 2px，颜色 `#abb5cc`，hover 变 `#3a84ff`，平角箭头（`block` marker）。`zIndex: -1` 确保在节点下方，不阻挡端口交互。
 - **连接点**：`connectionPoint: 'anchor'` + `anchor: 'center'`，连线直达端口中心，紧贴节点。
 
----
+<br>
 
 ## 命令系统
 
-所有 FlowModel 变更必须通过命令执行：
+所有 FlowModel 变更必须通过命令执行。每条命令通过 `CommandEnvelope` 包装，一个信封可包含多条原子命令，作为一次事务整体执行（撤销时整体回退）。
 
 ```typescript
 import { generateId } from '@blueking/flow-canvas';
+```
 
+**添加节点和连线：**
+
+```typescript
 editor.executeCommand({
   id: generateId(),
   source: 'user:panel',
   label: '添加节点',
   timestamp: Date.now(),
   commands: [
-    { type: 'node.add', node: { id: 'n1', type: 'task', position: { x: 100, y: 100 } } },
-    { type: 'edge.add', edge: { id: 'e1', source: { nodeId: 'n0' }, target: { nodeId: 'n1' } } },
+    { type: 'node.add', node: { id: 'n1', type: 'task', position: { x: 100, y: 100 }, label: '审批' } },
+    {
+      type: 'edge.add',
+      edge: { id: 'e1', source: { nodeId: 'n0', portId: 'right' }, target: { nodeId: 'n1', portId: 'left' } },
+    },
   ],
 });
 ```
 
+**删除节点（自动级联删除关联边）：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '删除节点',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.remove', nodeId: 'n1' }],
+});
+```
+
+**删除连线：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '删除连线',
+  timestamp: Date.now(),
+  commands: [{ type: 'edge.remove', edgeId: 'e1' }],
+});
+```
+
+**移动节点：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '移动节点',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.move', nodeId: 'n1', position: { x: 300, y: 200 } }],
+});
+```
+
+**更新节点结构字段（label、type、ports 等，不含 payload/extensions）：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '重命名节点',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.update', nodeId: 'n1', patch: { label: '新名称' } }],
+});
+```
+
+**按路径更新节点 payload（业务数据）：**
+
+```typescript
+// 设置 payload.config.timeout = 30
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '更新超时配置',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.set-payload', nodeId: 'n1', path: ['config', 'timeout'], value: 30 }],
+});
+
+// 设置整个 payload.config 对象
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '更新节点配置',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.set-payload', nodeId: 'n1', path: ['config'], value: { timeout: 30, retryable: true } }],
+});
+
+// 删除 payload 中的某个字段（value 传 undefined）
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '清除超时配置',
+  timestamp: Date.now(),
+  commands: [{ type: 'node.set-payload', nodeId: 'n1', path: ['config', 'timeout'], value: undefined }],
+});
+```
+
+**重连边端点：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '重连边',
+  timestamp: Date.now(),
+  commands: [
+    {
+      type: 'edge.reconnect',
+      edgeId: 'e1',
+      target: { nodeId: 'n2', portId: 'left' }, // 只改 target，source 不变
+    },
+  ],
+});
+```
+
+**更新边标签：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '更新边标签',
+  timestamp: Date.now(),
+  commands: [{ type: 'edge.label.update', edgeId: 'e1', labelId: 'label1', patch: { text: '条件成立' } }],
+});
+```
+
+**更新全局 meta：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '更新全局变量',
+  timestamp: Date.now(),
+  commands: [{ type: 'model.set-meta', path: ['variables', 'env'], value: 'production' }],
+});
+```
+
+**批量操作（一个信封包含多条命令，一次性执行）：**
+
+```typescript
+editor.executeCommand({
+  id: generateId(),
+  source: 'user:panel',
+  label: '批量删除选中',
+  timestamp: Date.now(),
+  commands: [
+    { type: 'edge.remove', edgeId: 'e1' },
+    { type: 'edge.remove', edgeId: 'e2' },
+    { type: 'node.remove', nodeId: 'n1' },
+    { type: 'node.remove', nodeId: 'n2' },
+  ],
+});
+```
+
+**处理命令执行结果：**
+
+```typescript
+const result = editor.executeCommand({
+  /* ... */
+});
+
+if (result.status === 'applied') {
+  console.log('执行成功，新模型:', result.flowModel);
+} else if (result.status === 'rejected') {
+  console.warn('被插件拒绝:', result.error?.reason);
+} else if (result.status === 'invalid') {
+  console.error('违反约束:', result.error?.reason);
+}
+```
+
 ### 命令类型一览
 
 | 命令                  | 说明                                        |
@@ -441,7 +598,7 @@ editor.executeCommand({
 
 `'user:drag'` | `'user:keyboard'` | `'user:toolbar'` | `'user:quick-add'` | `'user:panel'` | `'plugin'` | `'system'` | `'system:replace'`
 
----
+<br>
 
 ## 组件
 
@@ -487,18 +644,18 @@ editor.executeCommand({
 
 通过 schema `getBehavior` 返回值控制每个节点类型的工具栏行为：
 
-| 属性                 | 说明                                                     |
-| -------------------- | -------------------------------------------------------- |
-| `showActions`        | `false` → 该节点类型不显示整个工具栏                     |
-| `deletable`          | `false` → 隐藏删除按钮                                   |
-| `copyable`           | `false` → 隐藏复制和复制并插入按钮                       |
-| `disconnectable`     | `false` → 隐藏断开连线按钮                               |
-| `debuggable`         | `false` → 隐藏调试按钮（需全局 `showDebug` 也为 `true`） |
-| `deleteDisabled`     | `true` → 删除按钮可见但置灰不可点击                      |
-| `copyDisabled`       | `true` → 复制按钮置灰                                    |
-| `copyInsertDisabled` | `true` → 复制并插入按钮置灰                              |
-| `disconnectDisabled` | `true` → 断开连线按钮置灰                                |
-| `debugDisabled`      | `true` → 调试按钮置灰                                    |
+| 属性                 | 说明                                                                              |
+| -------------------- | --------------------------------------------------------------------------------- |
+| `showActions`        | `false` → 该节点类型不显示整个工具栏                                              |
+| `deletable`          | `false` → 隐藏删除按钮                                                            |
+| `copyable`           | `false` → 隐藏复制和复制并插入按钮                                                |
+| `disconnectable`     | `false` → 隐藏断开连线按钮                                                        |
+| `debuggable`         | `false` → 隐藏调试按钮（需全局 `showDebug` 也为 `true`）                          |
+| `deleteDisabled`     | `true` → 删除按钮可见但置灰不可点击                                               |
+| `copyDisabled`       | `true` → 复制按钮置灰                                                             |
+| `copyInsertDisabled` | `true` → 复制并插入按钮置灰                                                       |
+| `disconnectDisabled` | `true` → 断开连线按钮置灰                                                         |
+| `debugDisabled`      | `true` → 调试按钮置灰                                                             |
 | `actionsOffset`      | `{ x?: number; y?: number }` — 工具栏位置偏移（px），相对于默认位置（节点右下角） |
 
 按钮有效可见性 = 全局 `show*` AND 逐节点 `*able !== false`；
@@ -621,8 +778,7 @@ const schema: CanvasSchema = {
       component: TaskNode,
       getSize: () => ({ width: 180, height: 60 }),
       getBehavior: (node, ctx) => {
-        const hasOutEdge = Object.values(ctx.flowModel.edges)
-          .some(e => e.source.nodeId === node.id);
+        const hasOutEdge = Object.values(ctx.flowModel.edges).some((e) => e.source.nodeId === node.id);
         return {
           quickAddEnabled: !hasOutEdge, // 已有出边时隐藏"+"按钮
         };
@@ -642,18 +798,18 @@ const schema: CanvasSchema = {
 | sidebarWidth     | `number`              | `260`       | 侧边栏宽度（px）                                     |
 | hideSidebar      | `boolean`             | `false`     | 是否隐藏侧边栏                                       |
 | hideFooter       | `boolean`             | `false`     | 是否隐藏底部栏                                       |
-| editor           | `CanvasEditorContext` | `undefined` | 编辑器实例，传入后自动渲染内置 `CanvasNodePalette`    |
-| paletteItems     | `NodePaletteItem[]`   | `undefined` | 节点面板项列表，配合 `editor` 使用自定义面板节点列表  |
+| editor           | `CanvasEditorContext` | `undefined` | 编辑器实例，传入后自动渲染内置 `CanvasNodePalette`   |
+| paletteItems     | `NodePaletteItem[]`   | `undefined` | 节点面板项列表，配合 `editor` 使用自定义面板节点列表 |
 
-| Emit                    | 参数      | 说明             |
-| ----------------------- | --------- | ---------------- |
+| Emit                    | 参数      | 说明               |
+| ----------------------- | --------- | ------------------ |
 | update:sidebarCollapsed | `boolean` | 侧边栏收起状态变更 |
 
-| Slot    | 说明                                                          |
-| ------- | ------------------------------------------------------------- |
-| sidebar | 侧边栏内容（传入后覆盖内置 `CanvasNodePalette` 默认面板）    |
-| default | 主画布区域（放置 `CanvasRuntime` + `CanvasToolbar`）          |
-| footer  | 底部栏                                                        |
+| Slot    | 说明                                                      |
+| ------- | --------------------------------------------------------- |
+| sidebar | 侧边栏内容（传入后覆盖内置 `CanvasNodePalette` 默认面板） |
+| default | 主画布区域（放置 `CanvasRuntime` + `CanvasToolbar`）      |
+| footer  | 底部栏                                                    |
 
 #### 侧边栏的三种使用方式
 
@@ -699,12 +855,7 @@ const schema: CanvasSchema = {
     <template #sidebar>
       <div class="my-sidebar">
         <h3>节点库</h3>
-        <div
-          v-for="item in nodeItems"
-          :key="item.type"
-          ref="dndRefs"
-          class="my-sidebar__item"
-          :data-type="item.type">
+        <div v-for="item in nodeItems" :key="item.type" ref="dndRefs" class="my-sidebar__item" :data-type="item.type">
           {{ item.label }}
         </div>
       </div>
@@ -723,20 +874,23 @@ const schema: CanvasSchema = {
   ];
 
   // 通过 api.registerDndSource 注册拖拽源
-  watch(() => editor.api.value, (api) => {
-    if (!api) return;
-    for (const item of nodeItems) {
-      const el = document.querySelector(`[data-type="${item.type}"]`);
-      if (el) {
-        api.registerDndSource(el as HTMLElement, () => ({
-          id: generateId(),
-          type: item.type,
-          label: item.label,
-          position: { x: 0, y: 0 },
-        }));
+  watch(
+    () => editor.api.value,
+    (api) => {
+      if (!api) return;
+      for (const item of nodeItems) {
+        const el = document.querySelector(`[data-type="${item.type}"]`);
+        if (el) {
+          api.registerDndSource(el as HTMLElement, () => ({
+            id: generateId(),
+            type: item.type,
+            label: item.label,
+            position: { x: 0, y: 0 },
+          }));
+        }
       }
-    }
-  });
+    },
+  );
 </script>
 ```
 
@@ -759,9 +913,9 @@ const schema: CanvasSchema = {
 
 ```typescript
 interface NodePaletteItem {
-  type: string;   // 节点类型，对应 schema.nodeTypes 的 key
-  label: string;  // 显示名称
-  icon?: string;  // CSS 图标类名
+  type: string; // 节点类型，对应 schema.nodeTypes 的 key
+  label: string; // 显示名称
+  icon?: string; // CSS 图标类名
 }
 ```
 
@@ -809,7 +963,43 @@ const customItems = [
 | description | `string`                               | 操作说明，有值时 hover 显示 tooltip 气泡  |
 | onClick     | `(ctx: CanvasCallbackContext) => void` | 点击回调                                  |
 
----
+#### 通过 CSS 变量定制工具栏样式与位置
+
+`CanvasToolbar` 通过 CSS 自定义属性暴露了位置和外观的定制接口，使用方在父元素上设置对应变量即可覆盖默认值：
+
+| CSS 变量                          | 默认值                      | 说明                 |
+| --------------------------------- | --------------------------- | -------------------- |
+| `--flow-canvas-toolbar-top`       | `16px`                      | 工具栏距画布顶部距离 |
+| `--flow-canvas-toolbar-left`      | `16px`                      | 工具栏距画布左侧距离 |
+| `--flow-canvas-toolbar-right`     | `auto`                      | 工具栏距画布右侧距离 |
+| `--flow-canvas-toolbar-bottom`    | `auto`                      | 工具栏距画布底部距离 |
+| `--flow-canvas-toolbar-bg`        | `#565e7a`                   | 工具栏背景色         |
+| `--flow-canvas-toolbar-color`     | `#f5f7fa`                   | 工具栏文字/图标颜色  |
+| `--flow-canvas-toolbar-hover-bg`  | `rgba(255, 255, 255, 0.15)` | 按钮 hover 背景色    |
+| `--flow-canvas-toolbar-active-bg` | `rgba(255, 255, 255, 0.25)` | 按钮激活态背景色     |
+
+**示例 — 将工具栏移至画布底部居中，并更换背景色：**
+
+```vue
+<template>
+  <CanvasLayout :editor="editor" :palette-items="paletteItems" class="my-canvas-wrapper">
+    <CanvasRuntime :editor="editor" />
+    <CanvasToolbar :editor="editor" />
+  </CanvasLayout>
+</template>
+
+<style scoped>
+.my-canvas-wrapper {
+  --flow-canvas-toolbar-top: auto;
+  --flow-canvas-toolbar-bottom: 16px;
+  --flow-canvas-toolbar-left: 50%;
+  --flow-canvas-toolbar-right: auto;
+  --flow-canvas-toolbar-bg: #1a1a2e;
+}
+</style>
+```
+
+<br>
 
 ## 自定义节点组件
 
@@ -917,7 +1107,7 @@ const schema: CanvasSchema = {
 };
 ```
 
----
+<br>
 
 ## CanvasApi
 
@@ -947,7 +1137,7 @@ const schema: CanvasSchema = {
 | onGraphEvent(event, handler)                    | 监听 X6 底层事件，返回取消函数                   |
 | unsafeGetGraph()                                | 获取 X6 Graph 实例（谨慎使用）                   |
 
----
+<br>
 
 ## 内置插件
 
@@ -1003,7 +1193,7 @@ minimapPlugin({
 
 Cmd/Ctrl+C 复制选中节点/边，Cmd/Ctrl+V 粘贴（生成新 ID、偏移位置）。
 
----
+<br>
 
 ## 自定义插件
 
@@ -1065,7 +1255,7 @@ const myPlugin: CanvasPlugin = {
 };
 ```
 
----
+<br>
 
 ## 工具函数与底层 API
 
@@ -1085,7 +1275,7 @@ const emptyModel = createEmptyFlowModel();
 // { version: '1.0', nodes: {}, edges: {} }
 ```
 
----
+<br>
 
 ## 撤销/重做
 
@@ -1097,7 +1287,7 @@ editor.history.canRedo.value; // boolean
 editor.history.clear();
 ```
 
----
+<br>
 
 ## 事件类型 (CanvasUiEvent)
 
@@ -1119,7 +1309,7 @@ editor.history.clear();
 | node.quick-add           | nodeId, position        | 快捷添加弹层打开 |
 | node.action.quick-insert | sourceNodeId, newNodeId | 快捷插入节点     |
 
----
+<br>
 
 ## 公开类型参考
 
@@ -1193,11 +1383,11 @@ editor.history.clear();
 
 ### 默认 Schema
 
-| 类型                      | 说明                                  |
-| ------------------------- | ------------------------------------- |
-| `DefaultNodeTypeConfig`   | `createDefaultSchema` 的节点配置项    |
-| `DefaultSchemaOptions`    | `createDefaultSchema` 的选项          |
-| `DefaultSchemaResult`     | `createDefaultSchema` 的返回值        |
+| 类型                         | 说明                               |
+| ---------------------------- | ---------------------------------- |
+| `DefaultNodeTypeConfig`      | `createDefaultSchema` 的节点配置项 |
+| `DefaultSchemaOptions`       | `createDefaultSchema` 的选项       |
+| `DefaultSchemaResult`        | `createDefaultSchema` 的返回值     |
 | `DefaultToolbarItemsOptions` | `createDefaultToolbarItems` 的选项 |
 
 ### 历史与 Overlay