Vue3+AntV X6实战：如何给流程图节点添加悬浮按钮和隐藏连接桩（附完整代码）

Vue3 + AntV X6 交互增强实战：悬浮按钮与动态连接桩的精细化设计

流程图工具的核心价值，往往体现在那些不易察觉的交互细节里。想象一下，当用户面对一个复杂的业务流程图时，如果每个节点都堆满了默认可见的连接点和操作按钮，整个画布会显得多么杂乱无章。反之，如果能让这些辅助元素在需要时才优雅地出现，整个编辑体验的流畅度和专业感将得到质的飞跃。这正是我们今天要深入探讨的主题：如何利用 Vue3 的响应式能力与 AntV X6 强大的自定义 API，为流程图节点打造一套“智能”的交互界面——默认隐藏连接桩，仅在鼠标悬停时显示；同时，在节点特定区域（如右上角）集成悬浮式的操作按钮（如添加、删除），实现功能与视觉的完美平衡。这篇文章面向已经熟悉 Vue3 和 AntV X6 基础使用，希望进一步提升应用交互层级和用户体验的中高级前端开发者。我们将抛开官网的基础示例，直接切入实战中那些更具挑战性的设计思路与实现细节，并提供大量可直接集成到项目中的代码片段。

1. 核心理念：为何要隐藏连接桩与添加悬浮按钮？

在深入代码之前，我们有必要先厘清这种设计选择背后的逻辑。这绝非简单的“炫技”，而是基于真实用户体验的深思熟虑。

连接桩的“显”与“隐”：AntV X6 节点的连接桩（Port）是创建边的锚点。在默认配置下，它们通常是常驻显示的。这在节点数量少、结构简单时没有问题。然而，在一个中型乃至大型的流程图中，数十上百个节点同时显示所有连接桩，会导致画布上布满密密麻麻的小圆点，严重干扰用户对核心流程信息的阅读。将连接桩设置为默认隐藏（visibility: ‘hidden’），仅在鼠标悬停于节点上时显示，相当于提供了一种“按需取用”的机制。它保持了画布的视觉清爽，同时当用户真正需要进行连线操作时，交互入口又清晰可得。这种设计借鉴了现代 UI 中“内容优先，功能次之”的理念。

悬浮按钮的定位与事件：将关键操作（如添加子节点、删除当前节点）封装成节点内部的悬浮按钮，是另一种提升操作效率的策略。相比于在画布工具栏或右键菜单中寻找功能，将高频操作直接附着在操作对象上，符合“费茨定律”——目标越大、距离越近，操作越快越准。悬浮设计（通常通过 CSS 控制显示/隐藏）避免了按钮永久占据节点有限的空间，确保了节点主体内容（如节点名称、状态）的清晰展示。

将这两者结合，我们实际上是在构建一个动态的、上下文敏感的节点交互层。这个交互层平时保持静默，不打扰用户；一旦用户与节点发生意图交互（悬停、点击），相关功能便从容展开。实现这一层，需要综合运用 X6 的节点自定义、事件监听以及 Vue3 的响应式状态管理。

提示：在开始编码前，建议先在纸上或设计工具中规划好节点的视觉层次。明确哪些是始终可见的“内容层”，哪些是交互触发的“功能层”，这会让后续的代码结构更清晰。

2. 工程准备与自定义节点的基础架构

我们假设你已经有一个搭建好的 Vue3 项目（使用 Vite 或 Vue CLI），并安装了 @antv/x6 和 @antv/x6-vue-shape（如果需要在节点内使用 Vue 组件）。本节重点在于建立自定义节点的骨架。

首先，创建一个专门用于管理自定义节点注册的文件，例如 src/flow/graph/nodes.js。我们将在这里定义节点的“蓝图”。

// src/flow/graph/nodes.js
import { Graph, Shape } from '@antv/x6';

// 定义节点默认尺寸等常量
const NODE_DEFAULT_WIDTH = 180;
const NODE_DEFAULT_HEIGHT = 40;
const PORT_RADIUS = 4;
const BUTTON_RADIUS = 6;

/**
 * 注册一个具备悬浮按钮和隐藏连接桩的基础流程节点
 * 节点名称为 ‘custom-flow-node’
 */
export const registerCustomFlowNode = () => {
  Graph.registerNode(
    'custom-flow-node',
    {
      // 基础几何属性
      width: NODE_DEFAULT_WIDTH,
      height: NODE_DEFAULT_HEIGHT,
      // 标签结构 - 这是定义节点视觉构成的核心
      markup: [
        {
          tagName: 'rect',
          selector: 'body', // 为矩形主体指定一个选择器，便于后续样式绑定
        },
        {
          tagName: 'text',
          selector: 'label', // 文本标签选择器
        },
        // 按钮组：使用 <g> (分组) 元素包裹，方便整体控制
        {
          tagName: 'g',
          selector: 'btn-group',
          children: [
            {
              tagName: 'g',
              selector: 'btn-add',
              children: [
                { tagName: 'circle', selector: 'btn-add-circle' },
                { tagName: 'text', selector: 'btn-add-text' },
              ],
            },
            {
              tagName: 'g',
              selector: 'btn-delete',
              children: [
                { tagName: 'circle', selector: 'btn-delete-circle' },
                { tagName: 'text', selector: 'btn-delete-text' },
              ],
            },
          ],
        },
      ],
      // 属性样式定义
      attrs: {
        // 节点主体矩形
        body: {
          refWidth: '100%',
          refHeight: '100%',
          fill: '#f5f5f5', // 浅灰色填充
          stroke: '#d9d9d9', // 边框色
          strokeWidth: 1,
          rx: 6, // 圆角
          ry: 6,
        },
        // 节点标签文字
        label: {
          refX: '50%', // 水平居中