AntV X6 画布配置最佳实践：完整指南

AntV X6 画布配置最佳实践：完整指南

在使用 AntV X6 进行流程图、DAG（有向无环图）或其他图形编辑器开发时，合理的画布配置能够极大地提升用户体验和交互效率。本文将详细解析 AntV X6 画布的基础配置，涵盖 缩放、平移、节点连接、快捷键绑定 等关键功能，并提供优化建议，助你打造更流畅的图形编辑环境。

---

一、画布基础配置

在 AntV X6 中，Graph 组件的初始化配置项决定了整个画布的交互行为。以下是一个完整的 画布基础配置（baseConfig），并附带详细解析。

1. 画布基础设置

export const baseConfig = {
  translating: { restrict: true }, // 限制节点只能在画布范围内移动
  grid: true, // 开启网格
  background: { color: 'transparent' }, // 透明背景
}

• translating.restrict：防止节点被拖拽出画布范围。
• grid：开启网格，方便对齐操作。
• background.color：设置背景颜色，这里使用 transparent，也可以改为其他颜色。

---

2. 画布缩放与平移

mousewheel: {
  enabled: true, // 允许滚轮缩放
  zoomAtMousePosition: true, // 以鼠标位置为中心缩放
  modifiers: 'ctrl', // 需要按住 `ctrl` 键才可缩放
  minScale: 0.5, // 最小缩放比例
  maxScale: 2 // 最大缩放比例（保持一致）
},
scaling: {
  min: 0.5, // 画布最小缩放值
  max: 2 // 画布最大缩放值
},
panning: {
  enabled: true, // 允许拖动画布
  modifiers: 'alt' // 按住 `alt` 键拖动画布
}

• 缩放（mousewheel）

  • 需要 按住 ctrl 进行缩放，防止误操作。
  • zoomAtMousePosition 使得缩放以鼠标位置为中心，而不是画布中心。
  • minScale/maxScale 限制缩放范围，避免过大或过小的视图影响操作。

• 平移（panning）

  • 需要 按住 alt 进行拖拽，避免与节点拖拽操作冲突。

---

二、连接线与交互配置

1. 连接线规则

connecting: {
  router: {
    name: 'manhattan', // 直角连接方式
    args: { padding: 10, avoid: true } // 自动避开其他节点
  },
  connector: {
    name: 'rounded', // 圆角连接线
    args: { radius: 8 } // 圆角半径
  },
  snap: { radius: 20 }, // 连接点吸附半径
  connectionPoint: 'anchor', // 连接桩类型
  allowBlank: false, // 禁止连接到空白区域
  allowEdge: false, // 禁止边连接到另一条边
  allowNode: false, // 禁止边连接到节点中心
  allowPort: true, // 仅允许连接到连接桩
  highlight: true, // 高亮显示可连接点
}

• router 选择 manhattan（直角连接方式），并 启用避开功能。
• connector 选择 圆角连接，使连接线更美观。
• snap 设定 吸附半径，当连接线靠近连接桩时自动吸附。
• allowPort 只允许连接到 连接桩（port），而不是节点本体。

---

2. 连接线样式

createEdge() {
  return new Shape.Edge({
    attrs: {
      line: {
        stroke: '#2666FB', // 连接线颜色
        strokeWidth: 1, // 线条宽度
        targetMarker: { name: 'block', width: 12, height: 8 } // 目标端箭头
      }
    }
  });
}

• stroke 设定 连接线颜色。
• strokeWidth 设定 连接线粗细。
• targetMarker 设定 连接终点的箭头形状。

---

三、快捷键绑定

bindShortcuts(graph) {
  graph.bindKey(['meta+x', 'ctrl+x'], () => {
    const cells = graph.getSelectedCells();
    if (cells.length) {
      graph.cut(cells); // 剪切
    }
    return false;
  });

  graph.bindKey(['meta+v', 'ctrl+v'], () => {
    graph.paste(); // 粘贴
  });

  graph.bindKey(['meta+z', 'ctrl+z'], () => {
    graph.undo(); // 撤销
  });

  graph.bindKey(['meta+y', 'ctrl+y'], () => {
    graph.redo(); // 重做
  });

  graph.bindKey(['ctrl+1', 'meta+1'], () => {
    const zoom = graph.zoom();
    if (zoom < 1.5) {
      graph.zoom(0.1); // 放大
    }
  });

  graph.bindKey(['ctrl+2', 'meta+2'], () => {
    const zoom = graph.zoom();
    if (zoom > 0.5) {
      graph.zoom(-0.1); // 缩小
    }
  });
}

• 剪切（Ctrl + X）
• 粘贴（Ctrl + V）
• 撤销（Ctrl + Z）
• 重做（Ctrl + Y）
• 缩放快捷键（Ctrl + 1 / Ctrl + 2）

---

完整代码

import { Shape } from '@antv/x6';
import { Keyboard } from '@antv/x6-plugin-keyboard';

/**
 * AntV X6 的基础配置
 */
export const baseConfig = {
  // 限制节点只能在画布内移动
  translating: {
    restrict: true
  },
  // 开启网格
  grid: true,
  // 设置画布背景
  background: {
    color: 'transparent' // 透明背景
  },
  // 鼠标滚轮缩放设置
  mousewheel: {
    enabled: true, // 开启滚轮缩放
    zoomAtMousePosition: true, // 以鼠标位置为中心进行缩放
    modifiers: 'ctrl', // 需要按住 `ctrl` 才能缩放
    minScale: 0.5, // 最小缩放比例
    maxScale: 2 // 最大缩放比例（修改为 2，与 scaling 保持一致）
  },
  // 画布缩放范围
  scaling: {
    min: 0.5, // 最小缩放
    max: 2 // 最大缩放
  },
  // 画布平移设置
  panning: {
    enabled: true, // 开启画布平移
    modifiers: 'alt' // 需要按住 `alt` 才能平移
  },
  // 连接线设置
  connecting: {
    router: {
      name: 'manhattan', // Manhattan 路由方式
      args: {
        padding: 10, // 连接线与节点的间距
        avoid: true // 避开其他节点
      }
    },
    connector: {
      name: 'rounded', // 圆角连接线
      args: {
        radius: 8 // 圆角半径
      }
    },
    snap: { radius: 20 }, // 连接点吸附半径
    connectionPoint: 'anchor', // 连接点类型
    allowBlank: false, // 禁止连接到空白区域
    allowEdge: false, // 禁止连接线连接到另一条连接线
    allowNode: false, // 禁止连接到节点的中心
    allowPort: true, // 只允许连接到连接桩
    highlight: true, // 连接时高亮显示
    // 自定义创建边
    createEdge() {
      return new Shape.Edge({
        attrs: {
          line: {
            stroke: '#2666FB', // 连接线颜色
            strokeWidth: 1, // 连接线宽度
            targetMarker: {
              name: 'block', // 目标箭头形状
              width: 12,
              height: 8
            }
          }
        }
      });
    }
  },
  // 连接时的高亮效果
  highlighting: {
    magnetAdsorbed: {
      name: 'stroke',
      args: {
        attrs: {
          fill: '#028FA6',
          stroke: '#028FA6'
        }
      }
    }
  },
  // 允许的边样式
  edgeAvailable: {
    name: 'stroke',
    args: {
      padding: 4,
      color: '#ff0000', // 允许连接的边框颜色
      width: 3
    }
  },
  // 是否允许交互
  interacting: () => true,
  // 绑定快捷键
  bindShortcuts(graph) {
    graph.bindKey(['meta+x', 'ctrl+x'], () => {
      const cells = graph.getSelectedCells();
      if (cells.length) {
        graph.cut(cells); // 剪切选中的元素
      }
      return false;
    });

    graph.bindKey(['meta+v', 'ctrl+v'], () => {
      graph.paste(); // 粘贴元素
    });

    graph.bindKey(['meta+z', 'ctrl+z'], () => {
      graph.undo(); // 撤销操作
    });

    graph.bindKey(['meta+y', 'ctrl+y'], () => {
      graph.redo(); // 恢复操作
    });

    graph.bindKey(['ctrl+1', 'meta+1'], () => {
      const zoom = graph.zoom();
      if (zoom < 1.5) {
        graph.zoom(0.1); // 放大画布
      }
    });

    graph.bindKey(['ctrl+2', 'meta+2'], () => {
      const zoom = graph.zoom();
      if (zoom > 0.5) {
        graph.zoom(-0.1); // 缩小画布
      }
    });
  }
};

// 公共连接桩配置
export const cuPort = {
  groups: {
    top: {
      position: 'top',
      attrs: {
        circle: {
          r: 4, // 连接桩半径
          magnet: true, // 是否可连接
          stroke: '#5F95FF', // 连接桩边框颜色
          strokeWidth: 1, // 连接桩边框宽度
          fill: '#fff', // 连接桩填充色
          style: { visibility: 'hidden' } // 默认隐藏连接桩
        }
      }
    },
    right: {
      position: 'right',
      attrs: {
        circle: {
          r: 4,
          magnet: true,
          stroke: '#5F95FF',
          strokeWidth: 1,
          fill: '#fff',
          style: { visibility: 'hidden' }
        }
      }
    },
    bottom: {
      position: 'bottom',
      attrs: {
        circle: {
          r: 4,
          magnet: true,
          stroke: '#5F95FF',
          strokeWidth: 1,
          fill: '#fff',
          style: { visibility: 'hidden' }
        }
      }
    },
    left: {
      position: 'left',
      attrs: {
        circle: {
          r: 4,
          magnet: true,
          stroke: '#5F95FF',
          strokeWidth: 1,
          fill: '#fff',
          style: { visibility: 'hidden' }
        }
      }
    }
  },
  items: [
    { group: 'top' },
    { group: 'right' },
    { group: 'bottom' },
    { group: 'left' }
  ]
};

// 节点的类型列表
export const typeList = [
  { value: 1, label: '输入组件' },
  { value: 2, label: '输出组件' },
  { value: 3, label: '转换组件' }
];

总结

本文提供了一份 完整的 AntV X6 画布配置，包括 缩放、平移、连接规则、快捷键绑定、连接桩 等核心功能。希望这份指南能帮助你优化 X6 画布交互，让你的 DAG 流程图更加流畅、直观！ 🚀