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

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：流程图