logo

G6

  • 文档
  • API
  • 图表示例
  • 社区
  • 所有产品antv logo arrow
  • 5.0.48
  • 简介
  • 开始使用
    • 快速开始
    • 安装
    • 前端框架集成
      • 在 React 中使用
      • 在 Vue 中使用
      • 在 Angular 中使用
    • 详细教程
  • 图 Graph
    • Graph - 图
    • Options 配置项
    • 内置扩展
    • Extension - 扩展
  • 数据 Data
  • 元素 Element
    • 元素总览
    • 元素状态
    • 节点 Node
      • 节点总览
      • 内置节点
        • 节点通用配置项
        • Diamond 菱形
        • Donut 甜甜圈
        • Ellipse 椭圆形
        • Hexagon 六边形
        • Html HTML
        • Image 图片
        • Rect 矩形
        • Star 五角形
        • Triangle 三角形
        • Circle 圆形
      • 自定义节点
      • 使用 React 定义节点
    • 边 Edge
      • 边总览
      • 内置边
        • 边通用配置项
        • Cubic 三次贝塞尔曲线
        • CubicHorizontal 水平三次贝塞尔曲线
        • CubicVertical 垂直三次贝塞尔曲线
        • Line 直线
        • Polyline 折线
        • Quadratic 二次贝塞尔曲线
      • 自定义边
    • 组合 Combo
      • 组合总览
      • 内置组合
        • 组合配置项
        • Circle 圆形
        • Rect 矩形
      • 自定义 Combo
    • 图形 Shape
      • 图形 Shape 与 KeyShape
      • 原子 Shape 以及其属性
      • 复合 Shape 的设计与实现
  • 布局 Layout
    • 布局总览
    • 内置布局
      • 布局通用配置项
      • AntvDagre 布局
      • Circular 环形布局
      • ComboCombined 复合布局
      • CompactBox 紧凑树
      • Concentric 同心圆布局
      • D3Force 力导向布局
      • D3Force3D 3D 力导向布局
      • Dagre 布局
      • Dendrogram 生态树
      • Fishbone 鱼骨布局
      • Force 力导向布局
      • ForceAtlas2 力导向布局
      • Fruchterman 力导向布局
      • Grid 网格布局
      • Indented 缩进树
      • MDS 高维数据降维布局
      • Mindmap 脑图树
      • Radial 径向布局
      • Random 随机布局
      • Snake 蛇形布局
    • 自定义布局
  • 交互 Behavior
    • 交互总览
    • 内置交互
      • AutoAdaptLabel 标签自适应显示
      • BrushSelect 框选
      • ClickSelect 点击选中
      • CollapseExpand 展开/收起元素
      • CreateEdge 创建边
      • DragCanvas 拖拽画布
      • DragElement 拖拽元素
      • DragElementForce 力导向拖拽元素
      • FixElementSize 缩放画布时固定元素大小
      • FocusElement 聚焦元素
      • HoverActivate 悬停激活
      • LassoSelect 套索选择
      • OptimizeViewportTransform 优化视口变换
      • ScrollCanvas 滚动画布
      • ZoomCanvas 缩放画布
    • 自定义交互
  • 插件 Plugin
    • 插件总览
    • 内置插件
      • Background 背景
      • BubbleSets 气泡集
      • Contextmenu 上下文菜单
      • EdgeBundling 边绑定
      • EdgeFilterLens 边过滤镜
      • Fisheye 鱼眼放大镜
      • Fullscreen 全屏展示
      • GridLine 网格线
      • History 历史记录
      • Hull 轮廓包围
      • Legend 图例
      • Minimap 小地图
      • Snapline 对齐线
      • Timebar 时间条
      • Toolbar 工具栏
      • Tooltip 提示框
      • Watermark 水印
    • 自定义插件
  • 数据处理 Transform
    • 数据处理总览
    • 内置数据处理
      • MapNodeSize 动态调整节点大小
      • PlaceRadialLabels 径向标签
      • ProcessParallelEdges 平行边
    • 自定义数据处理
  • 主题 Theme
    • 主题总览
    • 自定义主题
    • 色板
    • 自定义色板
  • 动画 Animation
    • 动画总览
    • 自定义动画
  • 扩展阅读
    • 事件
    • 渲染器
    • 坐标系
    • 下载图片
    • 使用 iconfont
    • 使用 3D
    • 项目打包
  • 版本特性
    • 新版本特性
    • 升级到 5.0
  • 常见问题
  • 参与贡献

自定义 Combo

上一篇
Rect 矩形
下一篇
图形 Shape 与 KeyShape

Resources

Ant Design
Galacea Effects
Umi-React 应用开发框架
Dumi-组件/文档研发工具
ahooks-React Hooks 库

社区

体验科技专栏
seeconfSEE Conf-蚂蚁体验科技大会

帮助

GitHub
StackOverflow

more products更多产品

Ant DesignAnt Design-企业级 UI 设计语言
yuque语雀-知识创作与分享工具
EggEgg-企业级 Node 开发框架
kitchenKitchen-Sketch 工具集
GalaceanGalacean-互动图形解决方案
xtech蚂蚁体验科技
© Copyright 2025 Ant Group Co., Ltd..备案号:京ICP备15032932号-38

Loading...

G6 提供了两种 内置组合 类型:圆形组合和矩形 Combo 。但在复杂的业务场景中,你可能需要创建具有特定样式、交互效果或行为逻辑的自定义 Combo 。

开始之前:了解 Combo 的基本构成

在 G6 中,一个完整的 Combo 通常由以下几个部分组成:

  • key : Combo 的主图形,表示 Combo 的主要形状,如圆形、矩形等;
  • label :文本标签,通常用于展示 Combo 的名称或描述;
  • halo :主图形周围展示的光晕效果的图形;

Combo 的特殊性

Combo 不同于普通节点,它具有以下特性:

  1. 包含性: Combo 可以包含节点和其他 Combo ,形成层级结构
  2. 两种状态:展开(Expanded)和收起(Collapsed)状态
  3. 自适应大小:根据内部元素动态调整大小
  4. 拖拽行为:支持整体拖拽及内部元素拖入/拖出

自定义 Combo 的方式 选择合适的方式

创建自定义 Combo 的方式有两种途径:

1. 继承现有 Combo 类型 推荐

这是最常用的方式,你可以选择继承以下类型之一:

  • BaseCombo - 最基础的 Combo 类,提供 Combo 的核心功能
  • Circle - 圆形 Combo
  • Rect - 矩形 Combo

为什么选择这种方式?

  • 📌 代码量少:复用现有 Combo 的属性和方法,只需专注于新增功能
  • 📌 开发迅速:适合大多数项目需求,快速实现业务目标
  • 📌 易于维护:代码结构清晰,继承关系明确

2. 基于 G 图形系统从零开发 高级用法

如果现有 Combo 类型都不满足需求,你可以基于 G 的底层图形系统从零创建 Combo。

为什么选择这种方式?

  • 📌 最大自由度:完全控制 Combo 的每个细节,实现任意复杂效果
  • 📌 特殊需求:现有 Combo 类型无法满足的高度定制场景
  • 📌 性能优化:针对特定场景的性能优化

注意事项

从零开发的自定义 Combo 需要自行处理所有细节,包括图形绘制、事件响应、状态变化、展开/收起逻辑等,开发难度较大。这里可以直接参考 源码 进行实现。

三步创建你的第一个自定义 Combo

让我们从继承 BaseCombo 开始,实现一个自定义六边形 Combo :

import { Graph, register, BaseCombo, ExtensionCategory } from '@antv/g6';
// 定义收起状态的按钮路径
const collapse = (x, y, r) => {
return [
['M', x - r, y],
['a', r, r, 0, 1, 0, r * 2, 0],
['a', r, r, 0, 1, 0, -r * 2, 0],
['M', x - r + 4, y],
['L', x + r - 4, y],
];
};
// 定义展开状态的按钮路径
const expand = (x, y, r) => {
return [
['M', x - r, y],
['a', r, r, 0, 1, 0, r * 2, 0],
['a', r, r, 0, 1, 0, -r * 2, 0],
['M', x - r + 4, y],
['L', x - r + 2 * r - 4, y],
['M', x - r + r, y - r + 4],
['L', x, y + r - 4],
];
};
class HexagonCombo extends BaseCombo {
// 获取六边形的路径
getKeyPath(attributes) {
const [width, height] = this.getKeySize(attributes);
const padding = 10;
const size = Math.min(width, height) + padding;
// 计算六边形的顶点
const points = [];
for (let i = 0; i < 6; i++) {
const angle = (Math.PI / 3) * i;
const x = (size / 2) * Math.cos(angle);
const y = (size / 2) * Math.sin(angle);
points.push([x, y]);
}
// 构建SVG路径
const path = [['M', points[0][0], points[0][1]]];
for (let i = 1; i < 6; i++) {
path.push(['L', points[i][0], points[i][1]]);
}
path.push(['Z']);
return path;
}
// 获取主图形样式
getKeyStyle(attributes) {
const style = super.getKeyStyle(attributes);
return {
...style,
d: this.getKeyPath(attributes),
fill: attributes.collapsed ? '#FF9900' : '#F04864',
fillOpacity: attributes.collapsed ? 0.5 : 0.2,
stroke: '#54BECC',
lineWidth: 2,
};
}
// 绘制主图形
drawKeyShape(attributes, container) {
return this.upsert('key', 'path', this.getKeyStyle(attributes), container);
}
// 绘制展开/收起按钮,使用路径实现更精细的控制
drawCollapseButton(attributes) {
const { collapsed } = attributes;
const [width] = this.getKeySize(attributes);
const btnR = 8;
const x = width / 2 + btnR;
const d = collapsed ? expand(x, 0, btnR) : collapse(x, 0, btnR);
// 创建点击区域和按钮图形
const hitArea = this.upsert('hit-area', 'circle', { cx: x, r: 8, fill: '#fff', cursor: 'pointer' }, this);
this.upsert('button', 'path', { stroke: '#54BECC', d, cursor: 'pointer', lineWidth: 1.4 }, hitArea);
}
// 重写render方法,添加更多自定义图形
render(attributes, container) {
super.render(attributes, container);
this.drawCollapseButton(attributes, container);
}
// 使用生命周期钩子添加事件监听
onCreate() {
this.shapeMap['hit-area'].addEventListener('click', () => {
const id = this.id;
const collapsed = !this.attributes.collapsed;
const { graph } = this.context;
if (collapsed) graph.collapseElement(id);
else graph.expandElement(id);
});
}
}
// 注册自定义 Combo
register(ExtensionCategory.COMBO, 'hexagon-combo', HexagonCombo);
// 创建图实例并使用自定义 Combo
const graph = new Graph({
container: 'container',
height: 250,
data: {
nodes: [
{ id: 'node1', combo: 'combo1', style: { x: 100, y: 100 } },
{ id: 'node2', combo: 'combo1', style: { x: 150, y: 150 } },
{ id: 'node3', combo: 'combo2', style: { x: 300, y: 100 } },
{ id: 'node4', combo: 'combo2', style: { x: 350, y: 150 } },
],
combos: [
{ id: 'combo1', data: { label: 'Hexagon 1' } },
{ id: 'combo2', data: { label: 'Hexagon 2' }, style: { collapsed: true } },
],
},
node: {
style: {
fill: '#91d5ff',
stroke: '#1890ff',
lineWidth: 1,
},
},
combo: {
type: 'hexagon-combo',
style: {
padding: 20,
showCollapseButton: true,
labelText: (d) => d.data?.label,
labelPlacement: 'top',
},
},
behaviors: ['drag-element'],
});
graph.render();

第一步:编写自定义 Combo 类

import { BaseCombo } from '@antv/g6';
import type { BaseComboStyleProps } from '@antv/g6';
// 定义按钮路径生成函数
const collapse = (x, y, r) => {
return [
['M', x - r, y],
['a', r, r, 0, 1, 0, r * 2, 0],
['a', r, r, 0, 1, 0, -r * 2, 0],
['M', x - r + 4, y],
['L', x + r - 4, y],
];
};
const expand = (x, y, r) => {
return [
['M', x - r, y],
['a', r, r, 0, 1, 0, r * 2, 0],
['a', r, r, 0, 1, 0, -r * 2, 0],
['M', x - r + 4, y],
['L', x - r + 2 * r - 4, y],
['M', x - r + r, y - r + 4],
['L', x, y + r - 4],
];
};
class HexagonCombo extends BaseCombo {
// 获取六边形的路径
protected getKeyPath(attributes: Required<BaseComboStyleProps>) {
const [width, height] = this.getKeySize(attributes);
const padding = 10;
const size = Math.min(width, height) + padding;
// 计算六边形的顶点
const points = [];
for (let i = 0; i < 6; i++) {
const angle = (Math.PI / 3) * i;
const x = (size / 2) * Math.cos(angle);
const y = (size / 2) * Math.sin(angle);
points.push([x, y]);
}
// 构建 SVG 路径
const path = [['M', points[0][0], points[0][1]]];
for (let i = 1; i < 6; i++) {
path.push(['L', points[i][0], points[i][1]]);
}
path.push(['Z']);
return path;
}
// 获取主图形样式,直接使用路径数据
protected getKeyStyle(attributes: Required<BaseComboStyleProps>) {
const style = super.getKeyStyle(attributes);
return {
...style,
d: this.getKeyPath(attributes),
fill: attributes.collapsed ? '#FF9900' : '#F04864',
fillOpacity: attributes.collapsed ? 0.5 : 0.2,
stroke: '#54BECC',
lineWidth: 2,
};
}
// 绘制主图形,使用 path 类型直接传入样式对象
protected drawKeyShape(attributes: Required<BaseComboStyleProps>, container: Group) {
return this.upsert('key', 'path', this.getKeyStyle(attributes), container);
}
// 绘制收起/展开按钮,使用 SVG 路径实现更精细的控制
protected drawCollapseButton(attributes: Required<BaseComboStyleProps>) {
const { collapsed } = attributes;
const [width] = this.getKeySize(attributes);
const btnR = 8;
const x = width / 2 + btnR;
const d = collapsed ? expand(x, 0, btnR) : collapse(x, 0, btnR);
// 创建点击区域和按钮图形
const hitArea = this.upsert('hit-area', 'circle', { cx: x, r: 8, fill: '#fff', cursor: 'pointer' }, this);
this.upsert('button', 'path', { stroke: '#54BECC', d, cursor: 'pointer', lineWidth: 1.4 }, hitArea);
}
// 使用生命周期钩子方法绑定事件
onCreate() {
this.shapeMap['hit-area'].addEventListener('click', () => {
const id = this.id;
const collapsed = !this.attributes.collapsed;
const { graph } = this.context;
if (collapsed) graph.collapseElement(id);
else graph.expandElement(id);
});
}
}

第二步:注册自定义 Combo

import { ExtensionCategory } from '@antv/g6';
register(ExtensionCategory.COMBO, 'hexagon-combo', HexagonCombo);

第三步:应用自定义 Combo

const graph = new Graph({
// ...其他配置
combo: {
type: 'hexagon-combo', // 使用注册时的名称
style: {
padding: 20,
showCollapseButton: true,
labelText: (d) => d.data?.label,
labelPlacement: 'top',
},
},
// 由于我们自己实现了折叠展开功能,这里只需要拖拽行为
behaviors: ['drag-element'],
});

🎉 恭喜!你已经创建了第一个自定义 Combo 。

更进一步:理解 Combo 绘制的原理

Combo 与节点的区别

虽然 Combo 继承自 BaseNode,但有一些关键区别:

  1. 自适应大小: Combo 会根据内部元素自动计算合适的大小
  2. 展开/收起状态: Combo 有两种显示状态,并需要处理状态切换
  3. 层级结构: Combo 可以嵌套,形成层级关系
  4. 内部元素管理: Combo 需要管理其包含的节点和子 Combo

原子图形

G6 的 Combo 是由 G 图形系统 提供的图形原子单元绘制而成。原子图形的介绍请参考 元素 - 图形(可选) 文档。

所有这些图形都可通过 upsert() 动态创建或更新,并自动管理图形状态和生命周期。

元素基类

开始自定义 Combo 之前,你需要了解 G6 元素基类中的一些重要属性和方法:

属性

属性类型描述
shapeMapRecord<string, DisplayObject>当前元素下所有图形的映射表
animateMapRecord<string, IAnimation>当前元素下所有动画的映射表

方法

upsert(name, Ctor, style, container, hooks): 图形创建/更新

在创建自定义 Combo 时,你会频繁用到 upsert 方法。它是 "update or insert" 的缩写,负责添加或更新元素中的图形:

upsert(key: string, Ctor: { new (...args: any[]): DisplayObject }, style: Record<string, any>, container: DisplayObject);
参数类型描述
keystring图形的 key,即 shapeMap 中对应的 key。内置的 key 包括 'key' 'label' 'halo' 'icon' 'port' 'badge'
key 不应使用特殊符号,会基于该值转化为驼峰形式调用 getXxxStyle 和 drawXxxShape 方法(见 元素约定)
Ctor{ new (...args: any[]): DisplayObject }图形类
styleRecord<string, any>图形样式
containerDisplayObject挂载图形的容器

例如,插入一个固定位置的紫色圆形:

this.upsert(
'element-key', // 元素的唯一标识
'circle', // 图形类型,如 'rect', 'circle' 等
{ x: 100, y: 100, fill: '#a975f3' }, // 样式配置对象
container, // 父容器
);

为什么要使用 upsert 而不直接通过 container.appendChild() 创建图形?因为:

  1. 性能更好:当状态变化或数据更新时,会智能地复用已有图形,而不是删除再重建,大大提高了渲染性能
  2. 代码更简洁:不需要手动判断元素是否存在
  3. 便于管理:所有通过 upsert 创建的图形都会被记录在节点的 shapeMap 中,你可以通过 this.getShape(key) 轻松获取

render(attributes, container): 渲染组合的主入口

每个自定义 Combo 类都必须实现 render(attributes, container) 方法,它定义了该组合如何被"绘制"出来。你可以在这里使用各种原子图形,组合出你想要的结构。

render(style: Record<string, any>, container: Group): void;
参数类型描述
styleRecord<string, any>元素样式
containerGroup容器

getShape(name): 获取已创建的图形

有时,你需要在创建后修改某个子图形的属性,或者让子图形之间有交互关联。这时,getShape 方法可以帮你获取之前通过 upsert 创建的任何图形:

⚠️ 注意:图形的顺序很重要,如果图形 B 依赖图形 A 的位置,必须确保 A 先创建

元素约定

  • 使用约定属性

组合中约定的元素属性包括:

  • 通过 this.getKeySize(attributes) 获取组合的尺寸,考虑折叠状态和子元素

  • 通过 this.getContentBBox(attributes) 获取内容区域的边界盒

  • 通过 this.getComboPosition(attributes) 获取组合的当前位置,基于状态和子元素

  • 采用 getXxxStyle 和 drawXxxShape 配对的方式进行图形绘制

getXxxStyle 用于获取图形样式,drawXxxShape 用于绘制图形。通过该方式创建的图形支持自动执行动画。

其中 Xxx 是调用 upsert 方法时传入的 key 的驼峰形式。

  • 可通过 this.context 访问 Graph 上下文

生命周期钩子

提供了以下生命周期钩子函数,你可以在自定义 Combo 中重写这些方法,在关键时刻执行特定逻辑:

钩子函数触发时机典型用途
onCreate当组合创建后完成入场动画时绑定交互事件、初始化组合状态、添加外部监听器
onUpdate当组合更新后完成更新动画时更新依赖数据、调整相关元素、触发联动效果
onDestroy当组合完成退场动画并销毁后清理资源、移除外部监听器、执行销毁通知

状态响应

G6 元素设计中最强大的一点,是可以将 "状态响应" 与 "绘制逻辑" 分离。

你可以在组合配置中定义每种状态下的样式:

combo: {
type: 'custom-combo',
style: {
fill: '#f0f2f5',
stroke: '#d9d9d9'
},
state: {
selected: {
stroke: '#1890ff',
lineWidth: 2,
shadowColor: 'rgba(24,144,255,0.2)',
shadowBlur: 15,
},
hover: {
fill: '#e6f7ff',
},
},
}

切换状态的方法:

graph.setElementState(comboId, ['selected']);

这个状态会传入到 render() 方法的 attributes 中,由内部系统合并后的结果自动应用在图形上。

也可以根据状态自定义渲染逻辑:

protected getKeyStyle(attributes: Required<BaseComboStyleProps>) {
const style = super.getKeyStyle(attributes);
// 根据状态调整样式
if (attributes.states?.includes('selected')) {
return {
...style,
stroke: '#1890ff',
lineWidth: 2,
shadowColor: 'rgba(24,144,255,0.2)',
shadowBlur: 15,
};
}
return style;
}