antv-x6-editor

X6 图编辑引擎代码生成技能

核心约束（必须遵守）

X6 3.x 关键约束（强制）

• graph.render() 不存在：X6 3.x 中 new Graph() / addNode / addEdge / fromJSON 均自动渲染，代码中不得出现 graph.render()。
• 不得声明 container 变量：运行环境会作为函数参数注入 container。Graph 初始化只使用字符串字面量 container: 'container'，禁止 const/let/var container = ...，也禁止 document.getElementById('container')。
• 使用插件方法前必须先 graph.use(new Plugin(...)) 注册对应插件：graph.toPNG / toSVG / toJPEG 依赖 Export；graph.select / unselect 依赖 Selection；graph.undo / redo 依赖 History；graph.copy / paste / cut 依赖 Clipboard；graph.bindKey 依赖 Keyboard。未注册插件时对应方法不存在。
• 自定义 shape 必须先注册再使用：Graph.registerNode(name, def) / Graph.registerEdge(name, def) / Shape.HTML.register({ shape, ... }) 必须在首次 addNode / addEdge 之前完成。
• @antv/x6 仅导出 11 个插件类：Clipboard、Dnd、Export、History、Keyboard、MiniMap、Scroller、Selection、Snapline、Stencil、Transform。mousewheel、embedding、panning、connecting、translating、interacting、background、grid 是 new Graph() 的构造选项，不是插件，不得 import 同名类、不得 graph.use(new XxxClass())。例：滚轮缩放写在 Graph 构造中 mousewheel: { enabled: true, zoomAtMousePosition: true, modifiers: ['ctrl'] }。
• 节点/边动画使用 cell.animate(keyframes, options)（Web Animations API 风格）：X6 3.x 没有 node.transition(path, target, options) 方法。源码中 transition 仅作为 node.translate(tx, ty, { transition }) / node.rotate(deg, { transition }) 的 options 字段存在（boolean | KeyframeEffectOptions），并非独立方法。示例：

  // 通用动画
  node.animate(
    { fill: ['#fff', '#1890ff'], transform: ['scale(1)', 'scale(1.2)'] },
    { duration: 500, iterations: 1, fill: 'forwards' },
  );
  // 仅平移过渡
  node.translate(120, 0, { transition: { duration: 500, easing: 'ease-in-out' } });
  

  多步属性变更可用 graph.startBatch('animate'); cell.attr(...); graph.stopBatch('animate'); 包装。

初始化规范

• container 参数必填，必须使用字符串形式 container: 'container'，运行时环境会自动解析为 DOM 元素
• 必须设置背景色：background: { color: '#F2F7FA' }，所有画布都需要统一的浅蓝灰色背景
• 不要添加 grid 配置，除非用户明确要求显示网格
• 不要设置 width / height，除非用户明确指定画布尺寸；画布默认自适应容器大小
• 导入方式：import { Graph } from '@antv/x6'，仅导入实际使用到的类
• 禁止无条件导入 Shape：仅在使用 Shape.HTML.register() 等 Shape 静态方法时才导入 Shape
• 插件从 '@antv/x6' 直接导入，如 import { Graph, Selection, History } from '@antv/x6'
• 禁止使用 @antv/x6-plugin-xxx 独立包导入（已废弃）
• 标准初始化模板：

  import { Graph } from '@antv/x6';
  const graph = new Graph({
    container: 'container',
    background: { color: '#F2F7FA' },
  });
  

节点操作规范

• 优先使用 graph.addNode() 逐个添加节点，而非 graph.fromJSON() 批量导入（除非用户明确要求批量加载数据）
• 内置 shape：'rect'、'circle'、'ellipse'、'polygon'、'polyline'、'path'、'text'、'text-block'、'image'、'html'
• 节点样式通过 attrs 配置，遵循 SVG 属性命名
• 节点位置通过 x、y 设置（左上角坐标），尺寸通过 width、height 设置
• 默认节点样式（除非用户指定其他样式，所有节点统一使用此默认样式）：

  attrs: {
    body: { stroke: '#8f8f8f', strokeWidth: 1, fill: '#fff', rx: 6, ry: 6 },
  }
  

• 禁止在 attrs 中使用 CSS 属性名（如 background-color），必须用 SVG 属性（如 fill）

边操作规范

• 使用 graph.addEdge({ source, target, ... }) 添加边
• source/target 可以是：节点实例、节点 ID 字符串、{ cell: node, port: 'portId' } 对象、坐标 { x, y }
• 边样式：attrs: { line: { stroke, strokeWidth, strokeDasharray, targetMarker, sourceMarker } }
• 默认边样式（除非用户指定其他样式）：attrs: { line: { stroke: '#8f8f8f', strokeWidth: 1 } }
• 箭头：targetMarker: 'classic'（经典箭头）、'block'、'circle'、'diamond'
• 路由器：router: 'orth'（正交）、'manhattan'、'metro'、'er'
• 连接器：connector: 'rounded'（圆角）、'smooth'（贝塞尔曲线）、'jumpover'

连接桩（Ports）规范

• 连接桩定义在节点配置的 ports 字段中
• 端口组：ports: { groups: { groupName: { position, attrs, ... } }, items: [{ id, group }] }
• position 取值：'top'、'bottom'、'left'、'right'
• 端口是连线的锚点，设置 attrs: { circle: { magnet: true } } 允许从端口拖出连线
• 必须设置 magnet: true 才能从该端口发起或接收连线

交互配置规范

• 连线交互在 Graph 配置中通过 connecting 字段设置
• connecting: { allowBlank: false, router: 'orth', connector: 'rounded', createEdge() {...} }
• 节点移动限制：translating: { restrict: true } 或传函数限制区域
• 嵌入：embedding: { enabled: true } 允许节点拖入分组

插件使用规范

• 插件从 @antv/x6 导入，通过 graph.use(new Plugin(options)) 注册
• 可用插件：Selection、Snapline、History、Clipboard、Keyboard、Scroller、MiniMap、Transform、Export、Stencil、Dnd
• Selection: graph.use(new Selection({ enabled: true, rubberband: true }))
• Snapline: graph.use(new Snapline({ enabled: true }))
• History: graph.use(new History({ enabled: true }))
• Clipboard: graph.use(new Clipboard({ enabled: true }))
• Keyboard: graph.use(new Keyboard({ enabled: true }))
• Scroller: graph.use(new Scroller({ enabled: true }))
• MiniMap: graph.use(new MiniMap({ enabled: true, container: minimapContainer }))
• Transform: graph.use(new Transform({ resizing: { enabled: true }, rotating: { enabled: true } }))
• Export: graph.use(new Export())（注册后可调用 graph.toPNG() / graph.toSVG()）
• 动态控制：graph.enablePlugins('selection') / graph.disablePlugins('selection')
• 禁止在 Graph 构造函数中直接传入 selecting、snapline 等选项（3.x 不支持）

序列化规范

• 导出：const data = graph.toJSON() 返回 { cells: [...] } 对象
• 导入：graph.fromJSON(data) 加载整个图数据
• 清空：graph.clearCells() 清除所有元素
• 禁止手动构造 cells 数组中的内部字段（如 zIndex、parent），应通过 API 操作

事件规范

• 节点事件：graph.on('node:click', ({ node, e }) => {...})
• 边事件：graph.on('edge:click', ({ edge, e }) => {...})
• 画布事件：graph.on('blank:click', ({ e }) => {...})
• 变更事件：graph.on('node:moved', ({ node }) => {...})
• 事件回调参数是对象，不是位置参数：({ node, e }) 而非 (node, e)

导入规范

• 所有使用到的类都必须出现在 import 语句中：如使用 Selection，必须 import { Graph, Selection } from '@antv/x6'
• 禁止使用 Graph.Selection、Graph.Keyboard 等命名空间写法（不存在）
• 禁止使用未导入的类：new Selection(...) 必须对应 import { Selection } from '@antv/x6'
• import 自检清单（强制，输出代码前必须逐行核对）：对代码中每一个 new XxxYyy(...) 调用，XxxYyy 必须字面出现在第一行 import { ..., XxxYyy } from '@antv/x6' 的花括号内。常见漏写：Selection、Keyboard、History、Clipboard、Snapline、MiniMap、Transform、Scroller、Export、Stencil、Dnd、Shape（用到 Shape.HTML.register 时）。
• import 漏写为何会变成 Illegal constructor 等运行时错：评测/Playground 环境用 UMD 构建（window.X6）执行代码，而不是真正的 ES Module。Selection、Keyboard 等会根据 import 列表从 window.X6 解构出来；如果 import 漏写，标识符 Selection 会回退到 window.Selection（浏览器原生 Selection 接口），new Selection({...}) 会抛 Failed to construct 'Selection': Illegal constructor。Keyboard / History 等同理（会 is not a constructor）。
• import 漏写的标准修法：把所有用到的插件类合并到同一行 import { Graph, Selection, Keyboard, History, ... } from '@antv/x6';，不要分多行 import，也不要遗漏。

节点工具（Tools）规范

• 添加工具：node.addTools([{ name: 'button-remove', args: { x: 0, y: 0 } }]) 或 graph.addTools(node, [...])
• 移除工具：node.removeTools() 或 graph.removeTools(node)
• 检查工具：node.hasTools()
• 禁止使用 node.hideTools() / node.showTools()（3.x 不存在此 API）
• 悬停显示/隐藏工具的正确方式：

  graph.on('node:mouseenter', ({ node }) => {
    node.addTools([{ name: 'button-remove', args: { x: 0, y: 0 } }]);
  });
  graph.on('node:mouseleave', ({ node }) => {
    node.removeTools();
  });
  

渐变色规范

• X6 attrs 中 fill 支持渐变对象语法，禁止直接操作 graph.defs 或 document.createElementNS 创建 SVG 渐变
• 线性渐变正确写法：

  attrs: {
    body: {
      fill: {
        type: 'linearGradient',
        stops: [
          { offset: '0%', color: '#0000ff' },
          { offset: '100%', color: '#00ff00' },
        ],
      },
    },
  }
  

代码输出规范

• 必须输出纯 JavaScript，禁止使用 TypeScript 语法（如 private、类型注解 : string、as 类型断言）
• HTML 自定义节点使用 Shape.HTML.register({ shape, html, effect }) 注册自定义 shape，禁止使用 class extends Node 方式
• 禁止 Graph.registerHTMLComponent(name, factory) —— 这是 X6 2.x 旧 API，3.x 源码已无此方法。所有 HTML 节点统一通过 Shape.HTML.register 注册（详见 references/core/x6-core-html-shape.md）
• effect 数组指定哪些属性变化时触发重新渲染（如 ['data']）；纯静态展示节点不要加 effect
• HTML 节点正确写法：

  import { Graph, Shape } from '@antv/x6';
  Shape.HTML.register({
    shape: 'my-html',
    effect: ['data'],
    html(node) {
      const div = document.createElement('div');
      div.style.width = '100%';
      div.style.height = '100%';
      div.innerHTML = node.getData().content || '';
      return div;
    },
  });
  const graph = new Graph({ container: 'container' });
  graph.addNode({ shape: 'my-html', x: 100, y: 100, width: 200, height: 80, data: { content: '<div>Hello</div>' } });
  

Stencil 插件规范

• Stencil 通过 graph.use(new Stencil({ target: graph, groups: [...] })) 注册
• 注册后通过 graph.getPlugin('stencil') 获取实例，将 stencil.container 挂载到 DOM
• Stencil 内的节点模板使用 graph.createNode(...) 创建（非 graph.addNode），再通过 stencil.load(nodes, groupName) 加载

动态端口规范

• 使用 node.addPort() 动态添加端口时，必须在节点初始化时预定义对应的 ports.groups
• 如果没有预定义 group，端口无法正确定位，可能导致渲染异常
• 正确写法：

  const node = graph.addNode({
    ...,
    ports: {
      groups: {
        in: { position: 'left', attrs: { circle: { r: 4, magnet: true, stroke: '#8f8f8f', fill: '#fff' } } },
        out: { position: 'right', attrs: { circle: { r: 4, magnet: true, stroke: '#8f8f8f', fill: '#fff' } } },
      },
    },
  });
  node.addPort({ id: 'port1', group: 'out' });
  

• registerNode + addNode 的 ports 合并陷阱（强约束）：Graph.registerNode(name, { ports: { items: [{ id: 'in1', group: 'in' }] } }) 之后，如果再 graph.addNode({ shape: name, ports: { items: [{ id: 'in1', group: 'in' }] } })，X6 内部 Cell 构造时 ObjectExt.merge(defaults, metadata) 会按数组下标合并、node.addPorts 走的也是 [...current, ...new] 简单拼接，不会去重，运行时直接抛 Error: Duplicitied port id.。正确做法二选一：
  • 在 registerNode 里只声明 ports.groups，把 ports.items 留给 addNode / 后续 node.addPort 提供；
  • 或在 registerNode 里完整声明 ports.items，addNode 时不再传 ports.items（如需追加端口，调用 node.addPort({ id: '新id', group: 'xxx' })，且新 id 不能与 registry 里已声明的重名）。

DOM/CSS 操作规范（HTML 节点 / Stencil / 自定义工具）

• HTML 节点 html(node) 回调里给 DOM 设样式时，禁止直接写连字符属性：el.style.box-sizing = '...'、el.style.font-size = '...' 会被 JS 解析为 el.style.box - sizing = ...，抛 Invalid left-hand side in assignment。正确写法二选一：
  • 驼峰：el.style.boxSizing = 'border-box'、el.style.fontSize = '14px'、el.style.backgroundColor = '#fff'；
  • 方括号：el.style['box-sizing'] = 'border-box'、el.style['font-size'] = '14px'；
  • 多条样式优先用 el.style.cssText = 'box-sizing:border-box;font-size:14px;' 或 Object.assign(el.style, { boxSizing: 'border-box', fontSize: '14px' })。
• 同理，el.classList.add('...') / el.setAttribute('data-x', '...') 是合法 API；禁止 el.class = '...' / el['class-name'] = ...。

不存在的 API（禁止使用）

• 禁止 graph.scrollToCell() → 正确方式：graph.centerCell(cell) 滚动并居中到指定 cell
• 禁止 graph.highlightCell() / graph.highlightNode() → 正确方式：通过 node.attr('body/stroke', '#f00') 或添加 CSS class 实现高亮
• 禁止 Shape.Cylinder / Shape.Diamond 等不存在的内置 Shape → 用 'rect' + rx/ry 或 'polygon' 自定义
• 禁止 Shape.Edge.define() / Shape.Node.define() → 正确方式：Graph.registerEdge() / Graph.registerNode()
• 禁止 Shape.Group / Shape.Group.define() / new Shape.Group() → X6 3.x 的 Shape 命名空间没有 Group 导出（实际只有 Circle / Edge / Ellipse / HTML / Image / Path / Polygon / Polyline / Rect / TextBlock，运行时会报 Cannot read properties of undefined (reading 'define')）。父子分组的正确方式：直接 graph.addNode({ shape: 'rect', ... }) 创建一个普通节点作为父节点，再通过 parent.addChild(child) / parent.embed(child) 建立父子关系；或用 Graph.registerNode('my-group', { inherit: 'rect', markup: [...], attrs: {...} }) 注册一个自定义分组形状再 addNode({ shape: 'my-group' })。
• 禁止 把 Embedding 当插件 import / new / graph.use(new Embedding(...)) → X6 3.x 没有 Embedding 插件类（运行时会报 Embedding is not a constructor）。节点嵌入是 Graph 构造选项：new Graph({ container, embedding: { enabled: true, findParent: 'bbox', frontOnly: false, validate: ({ child, parent }) => true } })。Hover 高亮通过 highlighting.embedding 配置，嵌入/解除嵌入事件为 node:embedding / node:embedded。
• 禁止 history.batch() → 正确方式：graph.startBatch('custom'); ...; graph.stopBatch('custom'); 或 graph.batchUpdate(() => { ... })
• 禁止 graph.defs / graph.svgDoc / document.createElementNS('...', 'linearGradient' | 'defs' | 'marker') → X6 3.x 不暴露 graph.defs / graph.svgDoc，运行时会报 Cannot read properties of undefined。正确方式：
  • 节点/边普通 fill 渐变：直接用 attrs 中的渐变对象语法（fill: { type: 'linearGradient', stops: [...] }）
  • 自定义 marker 需要渐变填充：先 const id = graph.defineGradient({ type: 'linearGradient', stops: [{ offset: 0, color: '#f00' }, { offset: 1, color: '#0f0' }] })，再在 marker 对象里写 fill: \url(#${id})``
  • 自定义 marker / filter 同理使用 graph.defineMarker(options) / graph.defineFilter(options)

渲染输出规范（必须遵守）

• 画布初始化后必须存在至少一个 graph.addNode / graph.addEdge / graph.fromJSON 调用，确保画布有可视内容。即使用户 query 只描述了交互（panning / mousewheel / 插件等）配置，也必须自行补 2~3 个示例节点 + 1 条边作为渲染载体，否则视觉验证会被判定为「白屏」。
• 所有节点/边添加完成后，必须在末尾调用 graph.centerContent()（或在画布需要随内容缩放时使用 graph.zoomToFit({ padding: 20, maxScale: 1 })）。X6 默认不会自动居中，缺失该调用会导致内容偏向左上角、视觉评分不通过。两者二选一，不可同时调用。
• 多个交互（panning + mousewheel + Selection rubberband）同时启用时，必须用 modifiers 错开触发条件（例如：panning 用 'shift'，mousewheel 用 'ctrl'，rubberband 留空）。禁止把 'mouseWheel' 放进 panning.eventTypes 同时又启用 mousewheel，两者会争抢滚轮事件。

---

禁止的错误模式

❌ 使用已废弃的独立插件包

// 错误：独立插件包已废弃
import { Selection } from '@antv/x6-plugin-selection';
import { History } from '@antv/x6-plugin-history';

// 正确：从 @antv/x6 直接导入
import { Graph, Selection, History } from '@antv/x6';
const graph = new Graph({ container: 'container' });
graph.use(new Selection({ enabled: true, rubberband: true }));
graph.use(new History({ enabled: true }));

❌ 在构造函数中传入插件选项

// 错误：3.x 不支持构造函数选项模式
const graph = new Graph({
  container: 'container',
  selecting: { enabled: true },  // ❌
  snapline: { enabled: true },   // ❌
  history: { enabled: true },    // ❌
});

// 正确：使用 graph.use() 注册插件
import { Graph, Selection, Snapline, History } from '@antv/x6';
const graph = new Graph({ container: 'container' });
graph.use(new Selection({ enabled: true }));
graph.use(new Snapline({ enabled: true }));
graph.use(new History({ enabled: true }));

❌ 混淆 CSS 属性和 SVG 属性

// 错误：使用 CSS 属性名
attrs: {
  body: {
    'background-color': '#fff',  // ❌
    'border-radius': '6px',      // ❌
  }
}

// 正确：使用 SVG 属性名
attrs: {
  body: {
    fill: '#fff',               // ✅ 背景色
    rx: 6,                      // ✅ 圆角
    ry: 6,
    stroke: '#8f8f8f',          // ✅ 边框色
    strokeWidth: 1,             // ✅ 边框宽度
  }
}

❌ 缺少 container

// 错误：遗漏 container
const graph = new Graph({});

// 正确：container 必填
const graph = new Graph({ container: 'container' });

❌ 连接桩未设置 magnet

// 错误：端口无法连线
ports: {
  items: [{ id: 'port1', group: 'out' }],
  groups: {
    out: { position: 'right', attrs: { circle: { r: 5 } } }
  }
}

// 正确：设置 magnet: true
ports: {
  items: [{ id: 'port1', group: 'out' }],
  groups: {
    out: { position: 'right', attrs: { circle: { r: 5, magnet: true, stroke: '#8f8f8f' } } }
  }
}

❌ 事件回调使用位置参数

// 错误：参数不是位置传递
graph.on('node:click', (node, e) => { ... });

// 正确：解构对象参数
graph.on('node:click', ({ node, e }) => { ... });

---

基础结构模板

import { Graph } from '@antv/x6';

const graph = new Graph({
  container: 'container',
  background: { color: '#F2F7FA' },
});

const source = graph.addNode({
  shape: 'rect',
  x: 40,
  y: 40,
  width: 100,
  height: 40,
  label: 'Source',
  attrs: {
    body: { stroke: '#8f8f8f', strokeWidth: 1, fill: '#fff', rx: 6, ry: 6 },
  },
});

const target = graph.addNode({
  shape: 'rect',
  x: 300,
  y: 200,
  width: 100,
  height: 40,
  label: 'Target',
  attrs: {
    body: { stroke: '#8f8f8f', strokeWidth: 1, fill: '#fff', rx: 6, ry: 6 },
  },
});

graph.addEdge({
  source,
  target,
  attrs: {
    line: { stroke: '#8f8f8f', strokeWidth: 1 },
  },
});

// 内容居中：所有节点/边添加完成后调用，使画布内容相对于容器居中显示
// 如需缩放以适应容器，使用 graph.zoomToFit({ padding: 20, maxScale: 1 }) 替代
graph.centerContent();

---

场景选择指南

场景	推荐配置	关键特性
DAG 数据管道	ports + orth router + connecting	有向无环、端口连线
ER 实体关系图	HTML 节点 + er router	表格式节点、字段展示
流程图/审批流	菱形判断节点 + 分支边	条件分支、多路径
组织架构图	orth router + 树形布局	层级关系、折叠
血缘分析	左右布局 + smooth connector	多层流转、端口
网络拓扑	圆形节点 + 星型结构	设备类型、连接状态
状态机	圆形节点 + 边标签	状态转换、事件触发

---

内置节点类型

shape	形状	适用场景
rect	矩形	通用节点、流程步骤
circle	圆形	状态节点、端点
ellipse	椭圆	通用强调
polygon	多边形	菱形（判断）、六边形
text	纯文本	标注、注释
image	图片	图标节点
html	HTML	富文本、表格式节点

---

路由器与连接器

路由器（Router）— 决定边的路径走向

类型	效果	适用场景
normal	直线（默认）	简单图
orth	正交折线	流程图、DAG
manhattan	智能正交（绕障）	复杂布局
metro	地铁线风格	地铁图
er	ER 图专用	实体关系图

连接器（Connector）— 决定边的线条样式

类型	效果	适用场景
normal	直线段（默认）	简单图
rounded	圆角折线	流程图（推荐）
smooth	贝塞尔曲线	血缘图、关系图
jumpover	跨线跳跃	复杂交叉

---

插件速查

插件	注册方式	功能
Selection	graph.use(new Selection({ enabled: true, rubberband: true }))	框选节点
Snapline	graph.use(new Snapline({ enabled: true }))	对齐辅助线
History	graph.use(new History({ enabled: true }))	撤销/重做
Clipboard	graph.use(new Clipboard({ enabled: true }))	复制/粘贴
Keyboard	graph.use(new Keyboard({ enabled: true }))	快捷键绑定
Scroller	graph.use(new Scroller({ enabled: true }))	滚动画布
MiniMap	graph.use(new MiniMap({ enabled: true, container }))	小地图导航
Transform	graph.use(new Transform({ resizing: { enabled: true }, rotating: { enabled: true } }))	节点缩放/旋转
Export	graph.use(new Export())	导出 PNG/SVG
Stencil	graph.use(new Stencil({ target: graph, groups: [...] }))	侧边栏拖拽面板
Dnd	graph.use(new Dnd({ target: graph }))	拖拽创建节点