antv-g6-graph

G6 v5 图可视化代码生成技能

核心约束（必须遵守）

初始化规范

• container 参数必填，传入 DOM 元素 ID 字符串或 DOM 元素对象
• 使用 new Graph({...}) 构造函数，不得使用 new G6.Graph() (v4 写法)
• 所有配置在构造函数中一次性完成，不得事后多次调用配置方法覆盖
• graph.render() 返回 Promise，异步渲染；若需等待完成请 await graph.render()

数据结构规范

• 数据格式：{ nodes: [...], edges: [...], combos?: [...] }
• 每个节点必须有唯一 id（字符串）；业务数据放在 data 字段
• 边必须有 source 和 target，值为节点 id
• 禁止使用 v4 的 graph.data() 方法传数据

节点/边样式规范

• 样式通过 node.style / edge.style 配置，支持静态值和回调函数
• 回调函数签名：(datum: NodeData | EdgeData) => value
• 标签文本通过 style.labelText 设置（不是 label 或 labelCfg）
• 节点大小通过 style.size 设置（单个数值或 [width, height] 数组）

布局规范

• layout 配置放在 Graph 选项中：{ type: 'force', ... }
• force 布局不支持 preventOverlap / nodeSize（G6 v4 参数，v5 静默忽略）；防重叠请改用 d3-force + collide
• 树形布局（mindmap, compact-box, dendrogram, indented）需要树形数据或 treeToGraphData() 转换
• 力导向布局异步运行，graph.render() 后会持续迭代
• nodeStrength 必须为非负数（≥ 0），负值会导致布局计算异常或节点行为不可预测

交互行为规范

• behaviors 为字符串数组或配置对象数组
• 常用行为字符串简写：'drag-canvas', 'zoom-canvas', 'drag-element', 'click-select'
• G6 v5 移除了 Mode（模式）概念，所有 behavior 直接在数组中配置
• 复杂配置使用对象形式：{ type: 'click-select', multiple: true }

插件规范

• plugins 为数组，与 behaviors 类似
• 简写：'minimap', 'grid-line', 'tooltip'
• 复杂配置：{ type: 'tooltip', getContent: (e, items) => '...' }

---

禁止的错误模式

❌ 使用 v4 API

// 错误：v4 chainable API
const graph = new G6.Graph({ ... });
graph.data(data);
graph.render();
graph.node((node) => ({ ... }));  // v4 回调

// 正确：v5 构造函数
const graph = new Graph({
  container: 'container',
  data: { nodes: [...], edges: [...] },
  node: { style: { ... } },
});
graph.render();

❌ 错误的节点 data 结构

// 错误：直接在顶层放业务属性
{ id: 'node1', label: 'Node 1', value: 100 }

// 正确：业务属性放在 data 字段
{ id: 'node1', data: { label: 'Node 1', value: 100 } }

❌ 错误的标签配置

// 错误：v4 labelCfg
node: {
  labelCfg: { style: { fill: '#333' } }
}

// 正确：v5 style.labelText
node: {
  style: {
    labelText: (d) => d.data.label,
    labelFill: '#333',
    labelFontSize: 14,
  }
}

❌ behaviors 使用 Mode 概念

// 错误：v4 modes
modes: {
  default: ['drag-canvas', 'zoom-canvas'],
  edit: ['create-edge'],
}

// 正确：v5 直接 behaviors 数组
behaviors: ['drag-canvas', 'zoom-canvas', 'drag-element'],

❌ 自定义节点 render() 中读取 attributes.data → 白屏

// 错误：attributes 是计算后的样式对象，不含节点 data，访问 data.color 抛 TypeError
render(attributes, container) {
  const { data } = attributes;       // undefined
  const fill = data.color;           // TypeError → 白屏
}

// 正确：通过 node.style 回调把 data 字段映射为自定义样式属性
// ① Graph 配置
node: {
  type: 'my-node',
  style: { color: (d) => d.data.color },
},
// ② render() 中直接从 attributes 读取
render(attributes, container) {
  const { color = '#1783FF' } = attributes;  // ✅
}

❌ 使用 extend 注册自定义节点

// 错误：extend 已从 G6 v5 正式版移除，导入后调用会报 "extend is not a function"
import { Graph, extend } from '@antv/g6';
const extendedGraph = extend(Graph, {
  nodes: { 'my-node': MyNodeFn },
});

// 错误：v4 的 group.addShape() API
const MyNode = (node) => (model) => {
  const group = node.group();
  group.addShape('circle', { attrs: { r: 20 } });
};

// 正确：BaseNode 类 + register()
import { BaseNode, Circle, ExtensionCategory, Graph, register } from '@antv/g6';
class MyNode extends BaseNode {
  render(attributes, container) {
    super.render(attributes, container);
    this.upsert('key', Circle, { cx: 0, cy: 0, r: 20, fill: '#1783FF' }, container);
  }
}
register(ExtensionCategory.NODE, 'my-node', MyNode);
const graph = new Graph({ node: { type: 'my-node' } });

❌ 缺少 container

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

// 正确：container 必填，值为字符串 ID 或 DOM 元素
const graph = new Graph({ container: 'container' });
// 或传入 DOM 元素
const graph = new Graph({ container: document.getElementById('container') });

常见变体错误：container: container（把字符串 ID 当变量名使用，变量未定义 → ReferenceError → 白屏）

❌ autoFit: 'view' 配合异步力导向布局导致白屏

// 错误：combo-combined / force / d3-force 等布局是异步迭代的
// autoFit 在布局迭代开始前执行，节点全堆在原点，包围盒为零 → 缩放异常 → 白屏
const graph = new Graph({
  autoFit: 'view',          // ❌ 异步布局下不能在此设置
  layout: { type: 'combo-combined' },
});
graph.render();

// 正确：不设置 autoFit，在 AFTER_LAYOUT 事件后调用 fitView
import { Graph, GraphEvent } from '@antv/g6';
const graph = new Graph({
  layout: { type: 'combo-combined' },
});
graph.on(GraphEvent.AFTER_LAYOUT, () => graph.fitView({ padding: 20 }));
graph.render();

同步布局（dagre、grid、circular 等）不受此影响，可以直接用 autoFit: 'view'。

---

基础结构模板

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

const graph = new Graph({
  // 1. 容器
  container: 'container',       // DOM id 或 HTMLElement
  autoFit: 'view',              // 可选：'center' | 'view' | false

  // 2. 数据
  data: {
    nodes: [
       { id: 'n1', data: { label: '节点1' } },
       { id: 'n2', data: { label: '节点2' } },
    ],
    edges: [
       { source: 'n1', target: 'n2' },
    ],
  },

  // 3. 节点样式
  node: {
    type: 'circle',             // 节点类型
    style: {
      size: 40,
      fill: '#1783FF',
      stroke: '#fff',
      lineWidth: 2,
      labelText: (d) => d.data.label,
      labelPlacement: 'bottom',
    },
  },

  // 4. 边样式
  edge: {
    type: 'line',
    style: {
      stroke: '#aaa',
      lineWidth: 1,
      endArrow: true,
    },
  },

  // 5. 布局
  layout: {
    type: 'force',
    preventOverlap: true,
    nodeSize: 40,
  },

  // 6. 交互
  behaviors: ['drag-canvas', 'zoom-canvas', 'drag-element'],

  // 7. 插件（可选）
  plugins: ['grid-line'],

  // 8. 主题（可选）
  theme: 'light',               // 'light' | 'dark'
});

graph.render();

---

图类型选择指南

图类型	推荐布局	典型场景
网络图/关系图	force / fruchterman	社交网络、知识图谱
层次/流程图	dagre / antv-dagre	组织架构、工作流
树形图	compact-box / mindmap	文件树、思维导图
环形图	circular	循环依赖、环形关系
网格图	grid	棋盘布局、矩阵关系
同心圆	concentric	中心辐射关系
辐射布局	radial	以某节点为中心的辐射

---

内置节点类型

类型名	形状	适用场景
circle	圆形	通用节点，网络图
rect	矩形	流程图、UML
ellipse	椭圆	通用，强调纵向
diamond	菱形	决策节点
hexagon	六边形	蜂窝布局
triangle	三角形	特殊标记
star	五角星	特殊标记、评分
donut	环形	带进度的节点
image	图片	头像、图标节点
html	HTML	富文本自定义节点

---

内置边类型

类型名	形状	适用场景
line	直线	简单图、拓扑图
cubic	三次贝塞尔曲线	通用，弧形效果
cubic-horizontal	水平三次曲线	水平流程图
cubic-vertical	垂直三次曲线	垂直流程图
quadratic	二次贝塞尔曲线	轻量弧形边
polyline	折线	正交布局
loop	自环	节点自身的循环

---

内置布局算法

布局名	类型	特点
force	力导向	物理模拟，自然分布
d3-force	力导向	基于 D3，可配置力类型
fruchterman	力导向	快速，支持 GPU 加速
force-atlas2	力导向	大规模图，聚类效果好
dagre	层次	DAG，自动分层
antv-dagre	层次	AntV 优化版 Dagre
circular	环形	节点排列为圆形
concentric	同心圆	按属性值分环
grid	网格	规则网格排列
radial	辐射	以某节点为中心辐射
mds	降维	保持节点相对距离
random	随机	调试用
compact-box	树形	紧凑树，节省空间
mindmap	树形	思维导图风格
dendrogram	树形	树状图
indented	树形	缩进树

---

内置交互行为

行为名	描述
drag-canvas	拖拽画布
zoom-canvas	滚轮缩放画布
scroll-canvas	滚轮平移画布
drag-element	拖拽节点/边/combo
drag-element-force	力导向图中拖拽节点
click-select	点击选中元素
brush-select	框选元素
lasso-select	套索选择
hover-activate	悬停激活元素
collapse-expand	折叠/展开节点（树图）
create-edge	交互式创建边
focus-element	聚焦元素（缩放到指定元素）
fix-element-size	缩放时保持元素大小不变
auto-adapt-label	自动显示/隐藏标签（防重叠）
optimize-viewport-transform	大规模图视口优化

---

内置插件

插件名	描述
grid-line	网格背景线
background	背景颜色/图片
watermark	水印
minimap	缩略图导航
legend	图例
tooltip	元素提示框
toolbar	工具栏（缩放、撤销等）
contextmenu	右键菜单
history	撤销/重做
timebar	时间轴过滤
fisheye	鱼眼放大效果
edge-bundling	边捆绑
edge-filter-lens	边过滤镜头
hull	元素轮廓包围
bubble-sets	气泡集合
snapline	对齐辅助线
fullscreen	全屏

---

元素状态（States）

G6 v5 内置 5 种状态：selected、active、highlight、inactive、disabled

// 在 Graph 配置中为状态设置样式
node: {
  style: {
    fill: '#1783FF',
  },
  state: {
    selected: {
      fill: '#ff6b6b',
      stroke: '#ff4d4d',
      lineWidth: 3,
    },
    hover: {
      fill: '#40a9ff',
    },
  },
},

// 动态设置状态
graph.setElementState('node1', 'selected');
graph.setElementState('node1', ['selected', 'highlight']);
graph.setElementState('node1', []);  // 清除所有状态

---

主题系统

// 内置主题
const graph = new Graph({
  theme: 'light',   // 默认
  // theme: 'dark',
});

// 动态切换主题
graph.setTheme('dark');
graph.render();

---

数据操作 API

// 添加元素
graph.addNodeData([{ id: 'n3', data: { label: '新节点' } }]);
graph.addEdgeData([{ source: 'n1', target: 'n3' }]);

// 更新元素
graph.updateNodeData([{ id: 'n1', style: { fill: 'red' } }]);

// 删除元素
graph.removeNodeData(['n3']);

// 更新数据后需要重新渲染
graph.draw();

---

常见使用模式

数据驱动样式（推荐）

node: {
  style: {
    size: (d) => d.data.size || 30,
    fill: (d) => {
      const colorMap = { type1: '#1783FF', type2: '#FF6B6B', type3: '#52C41A' };
      return colorMap[d.data.type] || '#ccc';
    },
    labelText: (d) => d.data.name,
  },
},

调色板（Palette）映射

node: {
  palette: {
    type: 'group',       // 按分类映射颜色
    field: 'category',   // 数据中的分类字段
    color: 'tableau10',  // 内置色板名
  },
},

连续数值映射节点大小

transforms: [
  {
    type: 'map-node-size',
    field: 'value',
    range: [16, 60],
  },
],

平行边处理

transforms: [
  {
    type: 'process-parallel-edges',
    offset: 15,
  },
],
edge: {
  type: 'quadratic',
},

---

数据操作 API 速查

// 增
graph.addNodeData([{ id: 'n3', data: { label: '新节点' } }]);
graph.addEdgeData([{ source: 'n1', target: 'n3' }]);
graph.draw();

// 删
graph.removeNodeData(['n3']);   // 关联边自动删除
graph.draw();

// 改
graph.updateNodeData([{ id: 'n1', data: { label: '更新' } }]);
graph.draw();

// 查
const node = graph.getNodeData('n1');
const selected = graph.getElementDataByState('node', 'selected');
const zoom = graph.getZoom();

// 视口
await graph.fitView({ padding: 20 });
await graph.focusElement('n1', { duration: 500 });
await graph.zoomTo(1.5);

// 状态
graph.setElementState('n1', 'selected');
graph.setElementState('n1', []);          // 清除

// 销毁
graph.destroy();

---

事件监听速查

// 元素事件（node/edge/combo + 事件类型）
graph.on('node:click', (e) => console.log(e.target.id));
graph.on('edge:pointerover', (e) => graph.setElementState(e.target.id, 'active'));
graph.on('canvas:click', () => { /* 点击空白 */ });

// 生命周期事件
import { GraphEvent } from '@antv/g6';
graph.on(GraphEvent.AFTER_RENDER, () => console.log('渲染完成'));
graph.on(GraphEvent.AFTER_LAYOUT, () => console.log('布局完成'));

---

Reference 文档索引

核心

• g6-core-graph-init：Graph 初始化完整配置
• g6-core-data-structure：数据结构规范
• g6-core-graph-api：Graph 实例 API（增删改查、视口、状态）
• g6-core-events：事件系统（元素事件、画布事件、生命周期）
• g6-core-custom-element：自定义节点/边（register + BaseNode/BaseEdge）
• g6-core-transforms-animation：数据变换（map-node-size）与动画配置

节点类型

• g6-node-circle：圆形（通用）
• g6-node-rect：矩形（流程图）
• g6-node-image：图片节点
• g6-node-diamond-ellipse-hexagon：菱形/椭圆/六边形
• g6-node-star-triangle-donut：五角星/三角形/环形进度
• g6-node-html：HTML 富文本节点
• g6-node-react：React/Vue 自定义节点（@antv/g6-extension-react）

Combo

• g6-combo-overview：Combo 分组（circle/rect，折叠展开）

边类型

• g6-edge-line：直线边
• g6-edge-cubic：三次贝塞尔曲线边
• g6-edge-cubic-directional：有向三次曲线（cubic-horizontal 水平 / cubic-vertical 垂直）
• g6-edge-polyline：折线边
• g6-edge-quadratic-loop：二次曲线与自环边

布局

• g6-layout-force：力导向（force/d3-force）
• g6-layout-dagre：层次/流程图（dagre）
• g6-layout-circular：环形
• g6-layout-grid：网格
• g6-layout-mindmap：思维导图
• g6-layout-advanced：同心圆/辐射/mds/fruchterman
• g6-layout-combo-fishbone：复合布局（combo-combined）+ 鱼骨布局（fishbone）

数据变换

• g6-core-transforms-animation：map-node-size 与动画配置
• g6-transform-parallel-edges-radial：平行边处理（process-parallel-edges）+ 径向标签（place-radial-labels）

交互行为

• g6-behavior-click-select：点击选中
• g6-behavior-drag-element：拖拽节点
• g6-behavior-canvas-nav：画布拖拽+缩放
• g6-behavior-hover-activate：悬停激活
• g6-behavior-lasso-collapse：套索选择 + 折叠展开
• g6-behavior-create-edge-focus：创建边 + 聚焦元素
• g6-behavior-advanced：fix-element-size / auto-adapt-label / drag-element-force

插件

• g6-plugin-tooltip：悬停提示框
• g6-plugin-minimap：缩略图
• g6-plugin-contextmenu-toolbar：右键菜单 + 工具栏
• g6-plugin-history-legend：撤销重做 + 图例
• g6-plugin-fisheye-hull-watermark：鱼眼放大 + 轮廓包围 + 水印
• g6-plugin-timebar-gridline：时间轴 + 网格线
• g6-plugin-background-snapline：画布背景（background）+ 对齐线（snapline）
• g6-plugin-edge-bundling-bubble：边绑定（edge-bundling）+ 气泡集（bubble-sets）
• g6-plugin-fullscreen-title：全屏（fullscreen）+ 图标题（title）

状态与主题

• g6-state-overview：元素状态系统
• g6-theme-overview：主题系统

场景模板

• g6-pattern-network-graph：网络关系图
• g6-pattern-tree-graph：树形图/组织架构
• g6-pattern-flow-chart：流程图