ClawHub

AntV Skills

v1.0.0

G6 v5 图可视化代码生成技能，支持网络图、树形图、流程图等多种图类型的初始化、布局、交互和插件配置

0· 40· 1 versions· 0 current· 0 all-time· Updated 3h ago· MIT-0
byJoel Alan@lxfu1

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() 后会持续迭代

交互行为规范

  • 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({ width: 800, height: 600 });

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

常见变体错误：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
  width: 800,
  height: 600,
  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图片头像、图标节点
htmlHTML富文本自定义节点

内置边类型

类型名形状适用场景
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 文档索引

核心

节点类型

Combo

边类型

布局

数据变换

交互行为

插件

状态与主题

场景模板

Version tags

latestvk971dkr9wm9s43apdqdfnher2s85rrr5