g6/packages/site/docs/api/Group.zh.md

title	order
图形分组 Graphics Group	10

图形分组 Graphics Group（下文简称 Group） 类似于 SVG 中的 <g> 标签：Group  是用来组合图形对象的容器。在 Group  上添加变换（例如剪裁、旋转、放缩、平移等）会应用到其所有的子元素上。在 Group  上添加属性（例如颜色、位置等）会被其所有的子元素继承。此外， Group 可以多层嵌套使用，因此可以用来定义复杂的对象。关于 Group 更详细的介绍请参考 图形分组 Group 文档。

获取元素的 group

// 获取元素(节点/边/Combo)的图形对象的容器
const group = item.getContainer();

// 等价于
const group = item.get('group');

group 实例方法

group.addGroup(cfg)

向分组中添加新的分组。

参数

名称	类型	说明
cfg	Object	分组到配置项，非必须

其中，cfg 不是必须指定到，它包括以下字段：

名称	类型	说明
id	String	图形分组的唯一标识，非必须指定，指定则必须唯一
name	String	图形分组的标识，必须指定，在同一元素类型中必须唯一。另外，name 可以用于组内搜索到该元素：const shape = group.find(element => element.get('name') === 'shape-name')，find 函数用法见 find(fn)
capture	Boolean	非必须指定，该图形分组是否可以被鼠标事件捕捉到，即是否能够响应各鼠标事件。非必须指定
visible	Boolean	非必须指定，该图形分组是否可见。非必须指定，默认为 true
draggable	Boolean	非必须指定，该图形分组是否允许被拖拽。例如，自定义节点通过 addGroup 添加图形分组，当该图形分组的 draggable 值为 true 时，鼠标在该自定义节点的这个图形分组上才能够响应 dragstart，drag，与 dragend 事件；在实例化图时的 modes 中配置的 'drag-node' 交互才可以在该图形分组上进行拖拽时生效
zIndex	Number	非必须指定，该图形分组的视觉层次 z-index。非必须指定。指定后，调用 group.sort() 可以对组内所有图形根据各自 zIndex 进行视觉层次的排序

用法

// No configurations
group.addGroup();

// Configured
group.addGroup({
  id: 'groupId',
  draggable: true,
  // other configurations
});

group.addShape(type, cfgs)

向分组中添加新的图形。
⚠️ 注意: 在分组上添加的 clip， transform 等操作会影响到该分组中的所有图形。所有图形及其绘图属性请见 Shape Doc。

参数

名称	类型	说明
type	String	图元素类型，值可以为：'rect'、'circle'、'fan'、'ellipse'、'marker'、'image' 等，具体参考 Shape 的类型及属性 教程
cfg	Object	图元素的属性

其中，cfg 包括以下字段：

名称	类型	说明
attrs	Object	图形样式，必须配置，例如：{x: 0, y: 10, fill: '#0f0'}
name	String	图形的标识，必须指定，在同一元素类型中必须唯一。另外，name 可以用于组内搜索到该元素：const shape = group.find(element => element.get('name') === 'shape-name')，find 函数用法见 find(fn)
capture	Boolean	该图形是否可以被鼠标事件捕捉到，即是否能够响应各鼠标事件。非必须指定
visible	Boolean	该图形是否可见。非必须指定，默认为 true
draggable	Boolean	该图形是否允许被拖拽。例如，自定义节点通过 addShape 添加图形，当该图形的 draggable 值为 true 时，鼠标在该自定义节点的这个图形上才能够响应 dragstart，drag，与 dragend 事件；在实例化图时的 modes 中配置的 'drag-node' 交互才可以在该图形上进行拖拽时生效
zIndex	Number	该图形的视觉层次 z-index。非必须指定。指定后，调用 group.sort() 可以对组内所有图形根据各自 zIndex 进行视觉层次的排序

用法

group.addShape('rect', {
  attrs: {
    x: 0, // 必须配置
    y: 0, // 必须配置
    fill: 'red',
    stroke: 'red',
    shadowOffsetX: 10,
    shadowOffsetY: 10,
    shadowColor: 'blue',
    shadowBlur: 10,
    opacity: 0.8,
  },
  // 在 G6 3.3 及之后的版本中，必须指定 name，可以是任意字符串，但需要在同一个自定义元素类型中保持唯一性
  name: 'rect-shape',
  zIndex: 1,
});

group.contain(child)

该分组是否包含此元素。
返回值: Boolean

参数

名称	类型	说明
child	Group / Shape	子 Group 或 Shape 实例

用法

const has = group.contain(child);

group.find(fn)

根据指定条件返回对应元素，只返回符合条件的第一个元素。

参数

名称	类型	说明
fn	Function	自定义回调函数

用法

const child = group.find(function (item) {
  return item.attr('fill') === 'red'; // 找到首个填充为红色的图形
});

group.findById(id)

根据元素 ID 返回对应的实例。
返回值：Object。

参数

名称	类型	说明
id	String	Group 实例 ID

用法

const group1 = group.findById('group1');

group.findAll(fn)

返回所有符合条件的元素。
返回值: [ Object ]

参数

名称	类型	说明
fn	Function	自定义回调函数

用法

const children = group.findAll(function (item) {
  return item.get('id') < 10; // 获取所有id小于10的元素
});

group.getShape(x,y)

返回该坐标点最上层的元素。
返回值: Object

参数

名称	类型	说明
x	Number	x 坐标
y	Number	y 坐标

用法

// 获取 (10, 30) 坐标点上层的元素
const element = group.getShape(10, 30);

group.getFirst()

获取该分组的第一个子元素。
返回值: Object

用法

const child = group.getFirst();

// 等价于
const childrens = group.get('children');
const child = childrens[0];

group.getLast()

获取该分组的最后一个子元素。
返回值: Object

用法

const child = group.getLast();

// 等价于
const childrens = group.get('children');
const child = childrens[childrens.length - 1];

group.getChildByIndex(index）

返回第 index  个子元素，从 0 开始计数。
返回值: Object

参数

名称	类型	说明
index	Number	子元素的序号，默认为 0

用法

const child = group.getChildByIndex(2);

group.removeChild(child)

从分组中删除一个分组或一个图形。

参数

名称	类型	说明
child	Group / Shape	子 group 或 Shape 实例

用法

group.removeChild(child);

group.sort()

排序方法。
一般用于在设置子元素层叠顺序时使用。

典型使用场景：通过 group.addShape() 添加 shape 时，添加的每个 shape 都设置了 index，在最后调用 group.sort() 可以对添加的 shape 进行排序。

用法

group.sort();

group.clear()

清除该组的所有子元素。

用法

group.clear();