@blueking/flow-canvas 0.0.1-beta.1 → 0.0.1-beta.3

package/README.md

@@ -10,31 +10,67 @@
 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
+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
 ```
 
-### 可选依赖
+## 快速开始
 
-```bash
-npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
+### 零配置启动
+
+使用 `createDefaultSchema` 可零配置启动一个可拖拽、可连线的画布：
+
+```vue
+<template>
+  <CanvasLayout :editor="editor" :palette-items="paletteItems">
+    <CanvasRuntime :editor="editor" @ui-event="handleUiEvent" />
+    <CanvasToolbar :editor="editor" />
+  </CanvasLayout>
+</template>
+
+<script setup lang="ts">
+  import {
+    useCanvasEditor,
+    CanvasRuntime,
+    CanvasLayout,
+    CanvasToolbar,
+    createDefaultSchema,
+    createEmptyFlowModel,
+    selectionPlugin,
+    snaplinePlugin,
+    type CanvasUiEvent,
+  } from '@blueking/flow-canvas';
+  import '@blueking/flow-canvas/style';
+
+  const { schema, paletteItems } = createDefaultSchema();
+
+  const editor = useCanvasEditor({
+    initialFlowModel: createEmptyFlowModel(),
+    schema,
+    plugins: [selectionPlugin(), snaplinePlugin()],
+  });
+
+  function handleUiEvent(event: CanvasUiEvent) {
+    console.log('UI 事件:', event.type);
+  }
+</script>
 ```
 
-## 快速开始
+传入 `editor` prop 后，`CanvasLayout` 会自动在侧边栏渲染内置节点面板 `CanvasNodePalette`，用户可直接拖拽节点到画布。
+
+### 自定义 Schema
+
+如需完全控制节点/边类型，可手动定义 `CanvasSchema`：
 
 ```vue
 <template>
   <CanvasLayout>
     <template #sidebar>
-      <!-- 自定义侧边栏 -->
+      <MySidebar :editor="editor" />
     </template>
-    <CanvasRuntime :editor="editor" @ui-event="handleUiEvent">
-      <template #node-overlay="{ node, screenAnchors, api }">
-        <!-- 节点悬浮操作按钮 -->
-      </template>
-    </CanvasRuntime>
+    <CanvasRuntime :editor="editor" @ui-event="handleUiEvent" />
     <CanvasToolbar :editor="editor" />
   </CanvasLayout>
 </template>
@@ -116,7 +152,7 @@ npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
 </script>
 ```
 
----
+<br>
 
 ## 核心 API
 
@@ -151,13 +187,13 @@ npm install @antv/x6-plugin-dnd  # 拖拽建节点（DND）功能需要
 | replaceFlowModel(model)  | `(FlowModel) => void`                         | 整体替换流程模型               |
 | setMode(mode)            | `(CanvasMode) => void`                        | 切换模式                       |
 
----
+<br>
 
 ## FlowModel 数据结构
 
 ```typescript
 interface FlowModel {
-  version: '1.0';
+  version?: '1.0'; // 数据模型版本标识，可选，未传时引擎自动补全为 '1.0'
   nodes: Record<string, FlowNodeModel>; // 节点字典，key = nodeId
   edges: Record<string, FlowEdgeModel>; // 边字典，key = edgeId
   meta?: Record<string, unknown>; // 全局元数据
@@ -185,7 +221,7 @@ interface FlowEdgeModel {
 }
 ```
 
----
+<br>
 
 ## CanvasSchema 配置
 
@@ -197,7 +233,6 @@ interface CanvasNodeDefinition {
   getSize: (node) => { width; height };
   getPorts?: (node) => FlowPortModel[];
   getBehavior?: (node, ctx) => NodeBehaviorConfig;
-  getOverlayAnchors?: (node) => NodeOverlayAnchors;
   x6CellConfig?: Record<string, unknown>; // 透传给 X6 的额外配置
 }
 ```
@@ -223,29 +258,322 @@ interface CanvasEdgeDefinition {
 
 > **注意：** `labelRenderer` 字段在类型定义中存在但标记为 `@experimental`，当前版本尚未完整实现。如需自定义边标签样式，建议通过 `x6EdgeConfig.defaultLabel` 配置 X6 原生标签 markup。
 
-> **注意：** `labelRenderer` 字段在类型定义中存在但标记为 `@experimental`，当前版本尚未完整实现。如需自定义边标签样式，建议通过 `x6EdgeConfig.defaultLabel` 配置 X6 原生标签 markup。
+<br>
+
+## createDefaultSchema — 开箱即用的 Schema 工厂
 
----
+`createDefaultSchema` 提供内置的节点类型和边类型定义，可零配置快速启动画布。
+
+```typescript
+import { createDefaultSchema } from '@blueking/flow-canvas';
+
+const { schema, paletteItems } = createDefaultSchema(options?);
+```
+
+### DefaultSchemaOptions
+
+| 参数            | 类型                                    | 默认          | 说明                                           |
+| --------------- | --------------------------------------- | ------------- | ---------------------------------------------- |
+| nodeTypes       | `Record<string, DefaultNodeTypeConfig>` | 7 种内置类型  | 自定义节点类型列表，传入后替换内置类型         |
+| defaultEdgeType | `string`                                | `'manhattan'` | 默认连线类型，内置 `'manhattan'` 和 `'bezier'` |
+| edgeTypes       | `Record<string, CanvasEdgeDefinition>`  | -             | 额外/覆盖的边类型定义，会与内置类型合并        |
+
+### 返回值
+
+| 属性         | 类型                | 说明                                         |
+| ------------ | ------------------- | -------------------------------------------- |
+| schema       | `CanvasSchema`      | 可直接传给 `useCanvasEditor` 的 Schema 定义  |
+| paletteItems | `NodePaletteItem[]` | 可传给 `CanvasLayout` 的 `paletteItems` prop |
+
+### 内置节点类型
+
+不传 `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  |
+
+每种节点均使用内置 `DefaultNode` 组件渲染，自带上/右/下/左四个连接端口。
+
+自定义节点类型列表：
+
+```typescript
+const { schema, paletteItems } = createDefaultSchema({
+  nodeTypes: {
+    task: { label: '任务节点', width: 180, height: 60 },
+    approval: { label: '审批节点', icon: 'my-icon-class', width: 200, height: 60 },
+    notification: { label: '通知节点', width: 160, height: 50 },
+  },
+});
+```
+
+### 连线类型配置
+
+`createDefaultSchema` 内置两种连线类型：
+
+| 类型                | 路由        | 连接器                 | 说明                  |
+| ------------------- | ----------- | ---------------------- | --------------------- |
+| `manhattan`（默认） | `manhattan` | `rounded`（radius: 8） | 直角折线，圆角转弯    |
+| `bezier`            | 无          | `smooth`               | 贝塞尔曲线，平滑 S 形 |
+
+**切换为贝塞尔曲线连线：**
+
+```typescript
+const { schema, paletteItems } = createDefaultSchema({
+  defaultEdgeType: 'bezier',
+});
+```
+
+**使用自定义边类型：**
+
+```typescript
+const { schema, paletteItems } = createDefaultSchema({
+  defaultEdgeType: 'myEdge',
+  edgeTypes: {
+    myEdge: {
+      connector: 'normal',
+      style: (_edge, state) => ({
+        stroke: state.hovered ? 'red' : 'gray',
+        strokeWidth: 2,
+      }),
+    },
+  },
+});
+```
+
+**手动定义边类型（不使用 `createDefaultSchema`）：**
+
+在手动编写 `CanvasSchema` 时，同样可以通过 `edgeTypes` 和 `defaultEdgeType` 配置连线样式：
+
+```typescript
+const schema: CanvasSchema = {
+  nodeTypes: {
+    /* ... */
+  },
+  edgeTypes: {
+    bezier: {
+      connector: { name: 'smooth' },
+      style: (_edge, state) => ({
+        stroke: state.hovered ? '#3a84ff' : '#abb5cc',
+        strokeWidth: 2,
+      }),
+      x6EdgeConfig: {
+        attrs: {
+          line: {
+            stroke: '#abb5cc',
+            strokeWidth: 2,
+            targetMarker: { name: 'block', width: 8, height: 8 },
+          },
+        },
+      },
+    },
+    manhattan: {
+      router: { name: 'manhattan', args: { padding: 10, maxDirectionChange: 90 } },
+      connector: { name: 'rounded', args: { radius: 8 } },
+      style: (_edge, state) => ({
+        stroke: state.hovered ? '#3a84ff' : '#abb5cc',
+        strokeWidth: 2,
+      }),
+    },
+  },
+  defaultEdgeType: 'bezier',
+};
+```
+
+### 默认连线与端口样式
+
+- **端口**：半径 6px，背景 `#3a84ff`，1px 白色描边。默认隐藏（`visibility: hidden`），hover 节点时显示；拖拽连线时自动显示所有节点端口。
+- **连线**：宽度 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);
+}
+```
+
 ### 命令类型一览
 
 | 命令                  | 说明                                        |
@@ -270,7 +598,7 @@ editor.executeCommand({
 
 `'user:drag'` | `'user:keyboard'` | `'user:toolbar'` | `'user:quick-add'` | `'user:panel'` | `'plugin'` | `'system'` | `'system:replace'`
 
----
+<br>
 
 ## 组件
 
@@ -291,7 +619,6 @@ editor.executeCommand({
 
 | Slot            | Props                                            | 说明                                                        |
 | --------------- | ------------------------------------------------ | ----------------------------------------------------------- |
-| node-overlay    | `{ node, screenAnchors, api }`                   | 节点悬浮层，鼠标移入节点时显示                              |
 | quick-add-panel | `{ node, api, insertNodeToRight, closePopover }` | 快捷添加弹层内容，点击右侧"+"按钮时显示（默认显示提示文字） |
 
 #### 节点快捷操作工具栏
@@ -317,25 +644,26 @@ 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`；
 按钮禁用状态 = 逐节点 `*Disabled === true`。
 
 操作触发后通过 `@ui-event` 发出对应事件：`node.action.delete` / `node.action.copy` / `node.action.copy-insert` / `node.action.disconnect` / `node.action.debug`。
 
-#### 节点快捷添加按钮
+#### 节点快捷添加按钮（Quick Add）
 
 hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和拖拽发起连线。通过 `quickAdd` prop 进行全局配置：
 
@@ -373,22 +701,223 @@ hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和
 
 操作触发后通过 `@ui-event` 发出对应事件：`node.quick-add`（弹层打开时）/ `node.action.quick-insert`（插入成功时）。
 
+**完整的 quick-add-panel 使用示例：**
+
+```vue
+<template>
+  <CanvasLayout :editor="editor" :palette-items="paletteItems">
+    <CanvasRuntime :editor="editor" :quick-add="{ enabled: true }" @ui-event="handleUiEvent">
+      <template #quick-add-panel="{ node, insertNodeToRight, closePopover }">
+        <div class="quick-add-menu">
+          <div class="quick-add-menu__title">选择节点类型</div>
+          <div
+            v-for="item in quickAddNodeList"
+            :key="item.type"
+            class="quick-add-menu__item"
+            @click="handleQuickAdd(item, insertNodeToRight, closePopover)">
+            <i :class="item.icon" />
+            <span>{{ item.label }}</span>
+          </div>
+        </div>
+      </template>
+    </CanvasRuntime>
+    <CanvasToolbar :editor="editor" />
+  </CanvasLayout>
+</template>
+
+<script setup lang="ts">
+  import {
+    useCanvasEditor,
+    CanvasRuntime,
+    CanvasLayout,
+    CanvasToolbar,
+    createDefaultSchema,
+    createEmptyFlowModel,
+    generateId,
+    type FlowNodeModel,
+  } from '@blueking/flow-canvas';
+  import '@blueking/flow-canvas/style';
+
+  const { schema, paletteItems } = createDefaultSchema();
+  const editor = useCanvasEditor({ initialFlowModel: createEmptyFlowModel(), schema });
+
+  const quickAddNodeList = [
+    { type: 'empty', label: '空节点', icon: 'flow-canvas-icon canvas-jiedi' },
+    { type: 'parallel-gateway', label: '并行网关', icon: 'flow-canvas-icon canvas-bingxingwangguan' },
+  ];
+
+  function handleQuickAdd(
+    item: { type: string; label: string },
+    insertNodeToRight: (node: Omit<FlowNodeModel, 'position'>) => void,
+    closePopover: () => void,
+  ) {
+    insertNodeToRight({
+      id: generateId(),
+      type: item.type,
+      label: item.label,
+    });
+    closePopover();
+  }
+</script>
+```
+
+通过 `getBehavior` 可动态控制哪些节点显示"+"按钮：
+
+```typescript
+const schema: CanvasSchema = {
+  nodeTypes: {
+    end: {
+      component: EndNode,
+      getSize: () => ({ width: 88, height: 40 }),
+      getBehavior: () => ({
+        quickAddEnabled: false, // 结束节点不显示"+"按钮
+        deletable: false,
+      }),
+    },
+    task: {
+      component: TaskNode,
+      getSize: () => ({ width: 180, height: 60 }),
+      getBehavior: (node, ctx) => {
+        const hasOutEdge = Object.values(ctx.flowModel.edges).some((e) => e.source.nodeId === node.id);
+        return {
+          quickAddEnabled: !hasOutEdge, // 已有出边时隐藏"+"按钮
+        };
+      },
+    },
+  },
+};
+```
+
 ### CanvasLayout
 
-可选的布局骨架组件。
+可选的布局骨架组件，提供侧边栏 + 主画布 + 底栏的三栏布局。
+
+| Prop             | 类型                  | 默认        | 说明                                                 |
+| ---------------- | --------------------- | ----------- | ---------------------------------------------------- |
+| sidebarCollapsed | `boolean`             | `false`     | 侧边栏是否收起                                       |
+| sidebarWidth     | `number`              | `260`       | 侧边栏宽度（px）                                     |
+| hideSidebar      | `boolean`             | `false`     | 是否隐藏侧边栏                                       |
+| hideFooter       | `boolean`             | `false`     | 是否隐藏底部栏                                       |
+| editor           | `CanvasEditorContext` | `undefined` | 编辑器实例，传入后自动渲染内置 `CanvasNodePalette`   |
+| paletteItems     | `NodePaletteItem[]`   | `undefined` | 节点面板项列表，配合 `editor` 使用自定义面板节点列表 |
+
+| Emit                    | 参数      | 说明               |
+| ----------------------- | --------- | ------------------ |
+| update:sidebarCollapsed | `boolean` | 侧边栏收起状态变更 |
+
+| Slot    | 说明                                                      |
+| ------- | --------------------------------------------------------- |
+| sidebar | 侧边栏内容（传入后覆盖内置 `CanvasNodePalette` 默认面板） |
+| default | 主画布区域（放置 `CanvasRuntime` + `CanvasToolbar`）      |
+| footer  | 底部栏                                                    |
 
-| Prop             | 类型      | 默认    | 说明           |
-| ---------------- | --------- | ------- | -------------- |
-| sidebarCollapsed | `boolean` | `false` | 侧边栏是否收起 |
-| sidebarWidth     | `number`  | `260`   | 侧边栏宽度     |
-| hideSidebar      | `boolean` | `false` | 是否隐藏侧边栏 |
-| hideFooter       | `boolean` | `false` | 是否隐藏底部栏 |
+#### 侧边栏的三种使用方式
 
-| Slot    | 说明                                             |
-| ------- | ------------------------------------------------ |
-| sidebar | 侧边栏内容                                       |
-| default | 主画布区域（放置 CanvasRuntime + CanvasToolbar） |
-| footer  | 底部栏                                           |
+**方式一：自动渲染内置节点面板**
+
+传入 `editor` prop 且不提供 `sidebar` slot，`CanvasLayout` 自动在侧边栏渲染 `CanvasNodePalette`，用户可从面板拖拽节点到画布：
+
+```vue
+<CanvasLayout :editor="editor" :palette-items="paletteItems">
+  <CanvasRuntime :editor="editor" />
+</CanvasLayout>
+```
+
+通过 `paletteItems` prop 自定义面板中显示的节点类型列表：
+
+```vue
+<script setup lang="ts">
+  import { createDefaultSchema, useCanvasEditor, createEmptyFlowModel } from '@blueking/flow-canvas';
+
+  const { schema, paletteItems } = createDefaultSchema();
+  const editor = useCanvasEditor({ initialFlowModel: createEmptyFlowModel(), schema });
+
+  // 也可以手动指定面板项，只展示部分节点类型
+  const customPaletteItems = [
+    { type: 'start', label: '开始节点', icon: 'flow-canvas-icon canvas-kaishi' },
+    { type: 'end', label: '结束节点', icon: 'flow-canvas-icon canvas-stop' },
+    { type: 'empty', label: '空节点', icon: 'flow-canvas-icon canvas-jiedi' },
+  ];
+</script>
+
+<template>
+  <CanvasLayout :editor="editor" :palette-items="customPaletteItems">
+    <CanvasRuntime :editor="editor" />
+  </CanvasLayout>
+</template>
+```
+
+**方式二：通过 sidebar slot 完全自定义侧边栏**
+
+```vue
+<template>
+  <CanvasLayout>
+    <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">
+          {{ item.label }}
+        </div>
+      </div>
+    </template>
+    <CanvasRuntime :editor="editor" />
+  </CanvasLayout>
+</template>
+
+<script setup lang="ts">
+  import { ref, watch } from 'vue';
+  import { useCanvasEditor, CanvasRuntime, CanvasLayout, generateId } from '@blueking/flow-canvas';
+
+  const nodeItems = [
+    { type: 'task', label: '任务' },
+    { type: 'approval', label: '审批' },
+  ];
+
+  // 通过 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 },
+          }));
+        }
+      }
+    },
+  );
+</script>
+```
+
+**方式三：隐藏侧边栏**
+
+```vue
+<CanvasLayout hide-sidebar>
+  <CanvasRuntime :editor="editor" />
+</CanvasLayout>
+```
+
+### CanvasNodePalette
+
+内置的节点面板组件，支持拖拽节点到画布（DnD）。通常由 `CanvasLayout` 自动渲染，也可以单独使用。
+
+| Prop   | 类型                  | 必填 | 说明                                     |
+| ------ | --------------------- | ---- | ---------------------------------------- |
+| editor | `CanvasEditorContext` | 是   | 编辑器实例                               |
+| items  | `NodePaletteItem[]`   | 否   | 节点列表，不传时从 schema.nodeTypes 生成 |
+
+```typescript
+interface NodePaletteItem {
+  type: string; // 节点类型，对应 schema.nodeTypes 的 key
+  label: string; // 显示名称
+  icon?: string; // CSS 图标类名
+}
+```
 
 ### CanvasToolbar
 
@@ -404,12 +933,20 @@ hover 节点时，右侧端口显示为"+"按钮，支持点击弹出面板和
 
 工厂函数，用于获取默认工具栏项列表，便于自定义组合。
 
+撤销/重做（`undo` / `redo`）默认隐藏，可通过 `include` 恢复显示。
+
 ```typescript
 import { createDefaultToolbarItems } from '@blueking/flow-canvas';
 
-// 排除搜索，追加自定义项
-const items = [
-  ...createDefaultToolbarItems({ exclude: ['search'] }),
+// 默认不含撤销/重做
+const items = createDefaultToolbarItems();
+
+// 恢复显示撤销/重做
+const itemsWithHistory = createDefaultToolbarItems({ include: ['undo', 'redo'] });
+
+// 恢复撤销/重做，同时排除搜索，追加自定义项
+const customItems = [
+  ...createDefaultToolbarItems({ include: ['undo', 'redo'], exclude: ['search'] }),
   { id: 'my-tool', type: 'custom', icon: 'my-icon-class', onClick: handleClick },
 ];
 ```
@@ -426,7 +963,115 @@ const items = [
 | description | `string`                               | 操作说明，有值时 hover 显示 tooltip 气泡  |
 | onClick     | `(ctx: CanvasCallbackContext) => void` | 点击回调                                  |
 
----
+<br>
+
+## 自定义节点组件
+
+节点的渲染由 `CanvasNodeDefinition.component` 指定的 Vue 组件控制。组件内可通过 `inject('getNode')` 获取 X6 Node 实例，读取 FlowNodeModel 数据。
+
+### 基础节点组件
+
+```vue
+<!-- my-task-node.vue -->
+<template>
+  <div class="my-task-node" :class="{ 'is-selected': selected }">
+    <i v-if="icon" :class="icon" class="my-task-node__icon" />
+    <span class="my-task-node__label">{{ label }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { inject, ref, onMounted, onBeforeUnmount, computed } from 'vue';
+  import type { FlowNodeModel } from '@blueking/flow-canvas';
+
+  const getNode = inject<() => any>('getNode')!;
+
+  const nodeModel = ref<FlowNodeModel>();
+  const selected = ref(false);
+
+  const label = computed(() => nodeModel.value?.label ?? '');
+  const icon = computed(() => (nodeModel.value?.extensions as any)?.icon ?? '');
+
+  onMounted(() => {
+    const node = getNode();
+    nodeModel.value = node.getData() as FlowNodeModel;
+
+    node.on('change:data', ({ current }: { current: FlowNodeModel }) => {
+      nodeModel.value = current;
+    });
+  });
+</script>
+
+<style scoped>
+  .my-task-node {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+    height: 100%;
+    padding: 0 16px;
+    background: #fff;
+    border: 1px solid #dcdee5;
+    border-radius: 4px;
+    box-sizing: border-box;
+    cursor: pointer;
+  }
+  .my-task-node.is-selected {
+    border-color: #3a84ff;
+  }
+</style>
+```
+
+### 在 Schema 中注册节点组件
+
+```typescript
+import MyTaskNode from './components/my-task-node.vue';
+import MyGatewayNode from './components/my-gateway-node.vue';
+
+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,
+        quickAddEnabled: true,
+      }),
+    },
+    gateway: {
+      component: MyGatewayNode,
+      getSize: () => ({ width: 64, height: 64 }),
+      getPorts: () => [
+        { id: 'top', group: 'top' },
+        { id: 'right', group: 'right' },
+        { id: 'bottom', group: 'bottom' },
+        { id: 'left', group: 'left' },
+      ],
+      getBehavior: () => ({
+        copyable: false,
+        showActions: true,
+      }),
+    },
+  },
+  edgeTypes: {
+    default: {
+      connector: { name: 'smooth' },
+      style: (_edge, state) => ({
+        stroke: state.hovered ? '#3a84ff' : '#abb5cc',
+        strokeWidth: 2,
+      }),
+    },
+  },
+  defaultEdgeType: 'default',
+};
+```
+
+<br>
 
 ## CanvasApi
 
@@ -456,7 +1101,7 @@ const items = [
 | onGraphEvent(event, handler)                    | 监听 X6 底层事件，返回取消函数                   |
 | unsafeGetGraph()                                | 获取 X6 Graph 实例（谨慎使用）                   |
 
----
+<br>
 
 ## 内置插件
 
@@ -512,7 +1157,7 @@ minimapPlugin({
 
 Cmd/Ctrl+C 复制选中节点/边，Cmd/Ctrl+V 粘贴（生成新 ID、偏移位置）。
 
----
+<br>
 
 ## 自定义插件
 
@@ -574,7 +1219,7 @@ const myPlugin: CanvasPlugin = {
 };
 ```
 
----
+<br>
 
 ## 工具函数与底层 API
 
@@ -594,7 +1239,7 @@ const emptyModel = createEmptyFlowModel();
 // { version: '1.0', nodes: {}, edges: {} }
 ```
 
----
+<br>
 
 ## 撤销/重做
 
@@ -606,7 +1251,7 @@ editor.history.canRedo.value; // boolean
 editor.history.clear();
 ```
 
----
+<br>
 
 ## 事件类型 (CanvasUiEvent)
 
@@ -628,7 +1273,7 @@ editor.history.clear();
 | node.quick-add           | nodeId, position        | 快捷添加弹层打开 |
 | node.action.quick-insert | sourceNodeId, newNodeId | 快捷插入节点     |
 
----
+<br>
 
 ## 公开类型参考
 
@@ -649,7 +1294,7 @@ editor.history.clear();
 | 类型                    | 说明                                                                                                                                                             |
 | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `CanvasSchema`          | 画布配置（nodeTypes / edgeTypes）                                                                                                                                |
-| `CanvasNodeDefinition`  | 节点类型定义（component / getSize / getPorts / getBehavior / getOverlayAnchors）                                                                                 |
+| `CanvasNodeDefinition`  | 节点类型定义（component / getSize / getPorts / getBehavior）                                                                                                     |
 | `CanvasEdgeDefinition`  | 边类型定义（router / connector / style / labelDraggable）。`labelRenderer` 字段为 `@experimental`，当前未实现                                                    |
 | `CanvasCallbackContext` | 运行时上下文（api / flowModel / history / mode）                                                                                                                 |
 | `CanvasMode`            | 模式：`'edit'` / `'readonly'` / `'thumbnail'`                                                                                                                    |
@@ -698,6 +1343,16 @@ editor.history.clear();
 | `ConnectionValidator`       | 连接校验函数类型                                                                                                                                       |
 | `ConnectionValidateContext` | 连接校验上下文                                                                                                                                         |
 | `ConnectionValidateResult`  | 连接校验结果                                                                                                                                           |
+| `NodePaletteItem`           | 节点面板项（type / label / icon）                                                                                                                      |
+
+### 默认 Schema
+
+| 类型                         | 说明                               |
+| ---------------------------- | ---------------------------------- |
+| `DefaultNodeTypeConfig`      | `createDefaultSchema` 的节点配置项 |
+| `DefaultSchemaOptions`       | `createDefaultSchema` 的选项       |
+| `DefaultSchemaResult`        | `createDefaultSchema` 的返回值     |
+| `DefaultToolbarItemsOptions` | `createDefaultToolbarItems` 的选项 |
 
 ### 历史与 Overlay
 
@@ -706,8 +1361,6 @@ editor.history.clear();
 | `CanvasHistory`        | 历史管理器接口             |
 | `CanvasHistoryOptions` | 历史配置（maxHistorySize） |
 | `OverlayManager`       | Overlay 管理器接口         |
-| `NodeOverlayAnchors`   | 节点 Overlay 锚点定义      |
-| `OverlayAnchor`        | 单个锚点坐标               |
 
 ### 编辑器