Graph
Graph is the carrier of G6. All the operations about events, behaviors, items are mounted on the instance of Graph.
The life cycle of an instance of Graph is: Initialize -> Load data -> Render -> Update -> Destroy.
Initialize
G6.Graph
Configurations
Name | Type | Default | Description |
---|---|---|---|
container | String | HTMLElement | The DOM container of graph, it can be the id of a DOM element or the an HTML node. |
width | Number | undefined | The width of the canvas for graph with the unit 'px'. |
height | Number | undefined | The height of the canvas for graph with the unit 'px'. |
renderer | String | canvas | The engine for rendering. Options: 'canvas' or 'svg' . |
fitView | Boolean | false | Whether to fit the canvas to the view port. |
fitViewPadding | Array | Number | Takes effect only when fitView: true . It is the padding between canvas and the border of view port.- It can be a value, e.g. fitViewPadding: 20 , which means the padding to the top, left, right, bottom are the same.- Or an array, e.g. fitViewPadding: [ 20, 40, 50, 20 ] , the four values in the array indicate the padding to the top, right, bottom, left respectively. |
groupByTypes | Boolean | true | Whether to group the nodes and edges separately. When it is false, all the items (including nodes and edges) are in the same group, and the order/zindex of them are determined according to the order of their generation. |
autoPaint | Boolean | true | Whether to paint the graph automatically while item updated or view port changed. In order to enhance the performance, we recommend to turn off antoPaint when you are doing bulk operation on nodes or edges. This can be refered to setAutoPaint() . |
modes | Object | The interaction modes of this graph. Please refer to Interaction Mode for detail。 | |
nodeStateStyles | Object | {} | The node styles on different states, e.g. hover, selected. It is a new feature of G6 3.1. |
edgeStateStyles | Object | {} | The edge styles on different states, e.g. hover, selected. It is a new feature of G6 3.1. |
defaultNode | Object | {} | Default node configurations in global, including shape, size, color and so on. Its priority is lower than the configurations in data. |
defaultEdge | Object | {} | Default edge configurations in global, including shape, size, color and so on. Its priority is lower than the configurations in data. |
plugins | Array | [] | Plugins for graph. Please refer to Plugin for detail. |
animate | Boolean | false | Wheter activate the global animation. Which will take effect while changing layouts, changing data, and other global operations. |
animateCfg | Object | The configurations for global animation. Takes effect only when animate: true . |
|
animateCfg. onFrame |
Function | null | The callback function for every frame of animation. The path of custom animation for node can be defined here. The nodes will move linearly when onFrame is null. |
animateCfg. duration |
Number | 500 | Duration of animation with unit millisecond. |
animateCfg. easing |
String | easeLinear | The easing function name of animation. Please refer to ease in d3. |
minZoom | Number | 0.2 | The minimum zoom ratio. |
maxZoom | Number | 10 | The maximum zoom ratio. |
pixelRatio | Number | 1.0 | Pixel ratio. |
groupType | String | circle | Group type for nodes. Options: 'circle' or 'rect' . |
groupStyle | Object | Group style for nodes, please refer to Node Group for detail. | |
layout | Object | Configurations for layout. The type in it is the name of layout method with the options: 'random' , 'radial' , 'mds' , 'circular' , 'fruchterman' , 'force' , 'dagre' , 'concentric' , 'grid' . For more configurations for different layout methods, please refer to Layout API. |
⚠️Attention: In G6 3.1, we added two new configurations for graph: nodeStateStyles
and edgeStateStyles
. In the same time, we deleted nodeStyle
and edgeStyle
. To upgrate, replace nodeStyle
with nodeStateStyles
, and replace edgeStyle
with edgeStateStyles
, and keep the sub-configuration inside them.
Usage
Place the configurations in the paramter as below to instantiate a graph:
const graph = new G6.Graph({
container: '',
width: 500,
height: 500,
modes: {
default: ['drag-canvas'],
},
layout: {
type: 'radial',
unitRadius: 50,
center: [500, 300],
},
});
Load Data
data(data)
Load the data for graph.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | Object | true | Graph data, it should be an object containing an array of nodes and an array of edges. |
Usage
const data = {
nodes: [
{
id: 'node1',
label: 'node1',
},
{
id: 'node2',
label: 'node2',
},
],
edges: [
{
source: 'node1',
target: 'node2',
},
],
};
// graph is an instance of Graph
graph.data(data);
Render
render()
Render the graph with data onto the canvas.
Usage
graph.render();
renderCustomGroup(data, groupType)
Render a node group according to the data.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | Object | true | The data to be rendered |
groupType | String | true | Type of node group. Options: 'circle' or 'rect' |
Usage
const data = {
nodes: [
{
id: 'node1',
groupId: 'group1',
label: 'node1',
},
{
id: 'node2',
groupId: 'group1',
label: 'node2',
},
],
edges: [
{
source: 'node1',
target: 'node2',
},
],
groups: [
{
id: 'group1',
title: {
text: 'My Group 1',
stroke: '#444',
offsetX: -20,
offsetY: 30,
},
},
],
};
// graph is an instance of Graph
graph.renderCustomGroup(data, 'circle');
read(data)
Read the data and render the graph. It is equal to combining graph.data(data) and graph.render().
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | Object | true | Graph data, it should be an object containing an array of nodes and an array of edges. |
Usage
const data = {
nodes: [
{
id: 'node1',
label: 'node1',
},
{
id: 'node2',
label: 'node2',
},
],
edges: [
{
source: 'node1',
target: 'node2',
},
],
};
// graph is an instance of Graph
graph.read(data);
changeData(data)
Change the data source, and render the graph according to the new data.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | Object | true | Graph data, it should be an object containing an array of nodes and an array of edges. |
Usage
const data = {
nodes: [
{
id: 'node1',
label: 'node1',
},
{
id: 'node2',
label: 'node2',
},
],
edges: [
{
source: 'node1',
target: 'node2',
},
],
};
// graph is an instance of Graph
graph.changeData(data);
collapseGroup(groupId)
Collapse the group with groupId. After collapsing, the nodes and edges inside the group will be hided, the edges linking inside nodes and outside nodes will be linked to the group.
Parameters
Name | Type | Required | Description |
---|---|---|---|
groupId | String | true | The id of the group. |
Usage
graph.collapseGroup('groupId');
expandGroup(groupId)
Expand the group to show the inside nodes and edges, and the edges linking inside nodes and outside nodes will be restored.
Parameters
Name | Type | Required | Description |
---|---|---|---|
groupId | String | true | The id of the group. |
Usage
graph.expandGroup('groupId');
Update
addItem(type, model)
Add item(node, edge, or group) to the graph.
Parameters
Name | Type | Required | Description |
---|---|---|---|
type | String | true | The type of the item. Options: 'node' , 'edge' , and 'group' . |
model | Object | true | The data model of the item. When type: 'group' , refer to Create Node Group |
Usage
const model = {
id: 'node',
label: 'node',
address: 'cq',
x: 200,
y: 150,
style: {
fill: 'blue',
},
};
graph.addItem('node', model);
// Here is the model example for type = 'group'
const model = {
groupId: 'xxx000999',
nodes: ['123', '23'],
type: 'rect',
zIndex: 0,
title: {
text: 'group name',
},
};
graph.addItem('group', model);
add(type, model)
The same as addItem(type, model).
updateItem(item, model)
Update the item with new data model.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
cfg | Object | false | New data model. |
Usage
const model = {
id: 'node',
label: 'node',
address: 'cq',
x: 200,
y: 150,
style: {
fill: 'blue',
},
};
// Find the item instance by id
const item = graph.findById('node');
graph.updateItem(item, model);
update(item, model)
The same as updateItem(item, model).
removeItem(item)
Remove the item. When the item is the id of a group, this operation will delete the corresponding group.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
Usage
// Find the item instance by id
const item = graph.findById('node');
graph.removeItem(item);
remove(item)
The same as removeItem(item)。
refresh()
Refresh the canvas when the data is changed.
Usage
graph.refresh();
refreshItem(item)
Refresh the item.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
Usage
// Find the item instance by id
const item = graph.findById('node');
graph.refreshItem(item);
refreshPositions()
When the positions of nodes in their data models are changed, refresh the canvas to paint the nodes with new positions. It will update the edges in the same time.
Usage
graph.refreshPositions();
paint()
Repaint the canvas. Use it after changing the item's style or state.
Usage
const item = e.item;
const graph = this.graph;
const autoPaint = graph.get('autoPaint');
graph.setAutoPaint(false);
graph.setItemState(item, 'selected', true);
graph.paint();
graph.setAutoPaint(autoPaint);
setAutoPaint(auto)
Whether to repaint the canvas automatically after updating or deleting items.
Parameters
Name | Type | Required | Description |
---|---|---|---|
auto | Boolean | true | Whether to repaint the canvas automatically. |
Usage
const item = e.item;
const graph = this.graph;
const autoPaint = graph.get('autoPaint');
graph.setAutoPaint(false);
graph.setItemState(item, 'selected', true);
graph.paint();
graph.setAutoPaint(autoPaint);
Layout
There are several basic layout algorithms in G6 3.1. For more information, please refer to Layout API。
layout()
Re-layout the graph with current layout configurations in graph.
Usage
const graph = new G6.Graph({
container: 'mountNode',
width: 1000,
height: 600,
layout: {
type: 'force',
},
modes: {
default: ['drag-node'],
},
});
graph.data({
nodes: data.nodes,
edges: data.edges.map((edge, i) => {
edge.id = 'edge' + i;
return Object.assign({}, edge);
}),
});
graph.render();
function refreshDragedNodePosition(e) {
const model = e.item.get('model');
model.fx = e.x;
model.fy = e.y;
}
graph.on('node:dragstart', e => {
// Relayout when dragging the node
graph.layout();
refreshDragedNodePosition(e);
});
graph.on('node:drag', e => {
refreshDragedNodePosition(e);
});
graph.on('node:dragend', e => {
e.item.get('model').fx = null;
e.item.get('model').fy = null;
});
updateLayout(cfg)
Update the layout configurations.
- If there is
type
incfg
,type
is a string and it is different from current layout method,updateLayout(cfg)
will change the layout method and relayout; - If there is no
type
incfg
,updateLayout(cfg)
will relayout with current layout method and new layout configurations.
Parameters
Name | Type | Required | Description |
---|---|---|---|
cfg | Object | true | Configurations of new layout. |
Usage
const graph = new G6.Graph({
container: 'mountNode',
width: 1000,
height: 600,
modes: {
default: ['drag-canvas', 'drag-node'],
},
layout: {
type: 'circular',
center: [500, 300],
},
animate: true,
});
graph.data(data);
graph.render();
// configure the layout while instantializing the graph, and update the layout in somewhere you want.
graph.updateLayout({
radius: 200,
startAngle: Math.PI / 4,
endAngle: Math.PI,
divisions: 5,
ordering: 'degree',
});
Destroy
clear()
Clear all the items in the canvas. This function is used for reseting the data source and re-rendering the graph.
Usage
graph.clear();
destroy()
Destroy the graph.
Usage
graph.destroy();
State
showItem(item)
Show the item.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
Usage
// Find the item instance by id
const item = graph.findById('nodeId');
graph.showItem(item);
// equal to
graph.showItem('nodeId');
hideItem(item)
Hide the item.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
Usage
// Find the item instance by id
const item = graph.findById('nodeId');
graph.hideItem(item);
// Equal to
graph.hideItem('nodeId');
setItemState(item, state, enabled)
Set the item's state.
This function will emit events beforitemstatechange
and afteritemstatechange
.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
state | String | true | The value of state. State can be comstomized as selected, hover, actived, and so on. |
enabled | Boolean | true | Whether to activate the state. |
Usage
graph.setItemState('node1', 'selected', true);
clearItemStates(item, states)
Clear the states of the item. This function could clear multiple states in the same time.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
states | String / Array | null | false |
Usage
// Clear single state 'a' of the node
graph.clearItemStates(node, 'a');
// Clear multiple states of the node
graph.clearItemStates(node, ['a', 'b']);
// Clear all the states of the node
graph.clearItemStates(node);
node(nodeFn)
Set the style and other configurations for each node.
⚠️Attention: this funcion must be called before graph.render(). It does not take effect otherwise.
Parameters
Name | Type | Required | Description |
---|---|---|---|
nodeFn | Function | true | Return the configurations for each node. |
Usage
graph.node(node => {
return {
id: node.id,
shape: 'rect',
style: {
fill: 'blue',
},
};
});
graph.data(data);
graph.render();
edge(edgeFn)
Set the style and other configurations for each edge.
⚠️Attention: this funcion must be called before graph.render(). It does not take effect otherwise.
Parameters
Name | Type | Required | Description |
---|---|---|---|
edgeFn | Function | true | Return the configurations for each edge. |
Usage
graph.edge(edge => {
return {
id: edge.id,
shape: 'cubic-horizontal',
style: {
stroke: 'green',
},
};
});
graph.data(data);
graph.render();
Interaction
addBehaviors(behaviors, modes)
Add interaction behaviors to a mode or multiple modes.
Parameters
Name | Type | Required | Description |
---|---|---|---|
behaviors | String / Array | true | The name(s) of behavior(s) to be added. |
modes | String / Array | true | The name(s) of mode(s) |
Usage
// Add single behavior 'click-select' to a single mode 'default'
graph.addBehaviors('click-select', 'default');
// Add multiple behaviors to single mode 'default'
graph.addBehaviors(['brush-select', 'click-select'], 'default');
// Add single behavior 'brush-select' to multiple modes
graph.addBehaviors('brush-select', ['default', 'select']);
// Add multiple behaviors to multiple modes
graph.addBehaviors(['brush-select', 'click-select'], ['default', 'select']);
removeBehaviors(behaviors, modes)
Remove behavior(s) from mode(s).
Parameters
Name | Type | Required | Description |
---|---|---|---|
behaviors | String / Array | true | The name(s) of behavior(s) to be removed. |
modes | String / Array | true | The name(s) of mode(s). |
Usage
// remove single behavior 'click-select' from single mode 'default'
graph.removeBehaviors('click-select', 'default');
// remove multiple behaviors from single mode 'default'
graph.removeBehaviors(['brush-select', 'click-select'], 'default');
// remove single behavior 'brush-select' from multiple modes
graph.removeBehaviors('brush-select', ['default', 'select']);
// remove multiple behaviors from multiple modes
graph.removeBehaviors(['brush-select', 'click-select'], ['default', 'select']);
setMode(mode)
Switch the interaction mode of graph. For example, switch from edit mode to read-only mode.
Parameters
Name | Type | Required | Description |
---|---|---|---|
mode | String | true | The name of the mode. |
Usage
const graph = new G6.Graph({
container: div,
width: 500,
height: 500,
pixelRatio: 2,
modes: {
default: [...],
custom: [...]
}
})
graph.setMode('custom')
getCurrentMode()
Get the current mode.
Return
- Type of return value: String;
- The return value indicates the current mode.
Usage
// The return value is the current interaction mode
const mode = graph.getCurrentMode();
getZoom()
Get the current zoom ratio.
Return
- Type of return value: Number;
- The return value indicates the current zoom ratio of view port. The default value is 1.
Usage
// The return value indicates the current zoom ratio
const zoom = graph.getZoom();
zoom(ratio, center)
Change the zoom ratio. The parameter ratio is the related ratio about the current canvas.
Parameters
Name | Type | Required | Description |
---|---|---|---|
ratio | Number | true | Zoom ratio. |
center | Object | false | Zoom at the center with x and y . If the center is ignored, this operation will zoom the graph with the current graph center. |
Usage
// Zoom at center (100, 100) with ratio 3
graph.zoom(3, { x: 100, y: 100 });
// Zoom at graph center with ratio 0.5
graph.zoom(0.5);
zoomTo(toRatio, center)
Zoom the canvas at the center to a fixed ratio.
Parameters
Name | Type | Required | Description |
---|---|---|---|
toRatio | Number | true | Fixed zoom ratio. |
center | Object | false | Zoom at the center with x and y . If the center is ignored, this operation will zoom the graph with the current graph center. |
Usage
// Zoom at center (100, 100) with ratio 3
graph.zoomTo(3, { x: 100, y: 100 });
// Zoom at graph center with ratio 0.5
graph.zoomTo(0.5);
focusItem(item)
Move the graph to center at the item. This operation can be used as easing animation after searching a node.
Parameters
Name | Type | Required | Description |
---|---|---|---|
item | String / Object | true | The id or the instance of the item. |
Usage
graph.focusItem(item);
changeSize(width, height)
Change the size of the canvas.
Parameters
Name | Type | Required | Description |
---|---|---|---|
width | Number | true | The width of the canvas. |
height | Number | true | The height of the canvas. |
Usage
graph.changeSize(600, 350);
translate(dx, dy)
Move the canvas with relative displacement.
Parameters
Name | Type | Required | Description |
---|---|---|---|
dx | Number | true | Displacement in the horizontal direction. |
dy | Number | true | Displacement in the vertical direction. |
Usage
graph.translate(100, 100);
moveTo(x, y)
Move the canvas to a fixed position.
Parameters
Name | Type | Required | Description |
---|---|---|---|
x | Number | true | Displacement in the horizontal direction. |
y | Number | true | Displacement in the vertical direction. |
Usage
graph.moveTo(200, 300);
fitView(padding)
Fit the graph to the view port.
Parameters
Name | Type | Required | Description |
---|---|---|---|
padding | Number / Array | false | The padding of [top, right, bottom, left]. |
Usage
// When padding is a number, top = right = bottom = left = 20
graph.fitView(20);
// Equal to graph.fitView(20)
graph.fitView([20]);
// When padding is an array with 2 values, top = bottom = 20, right = left = 10
graph.fitView([20, 10]);
// When padding is an array with four values
graph.fitView([20, 10, 20, 15]);
Search
find(type, fn)
Find single item according to a rule.
Parameters
Name | Type | Required | Description |
---|---|---|---|
type | String | true | Type of the item. Options: 'node' , 'edge' . |
fn | Function | true | Rule for searching. |
Return
- Type of the return value: Object;
- If there are items that match the rule, return the first one. Return
undefined
otherwise.
Usage
const findNode = graph.find('node', node => {
return node.get('model').x === 100;
});
findById(id)
Find an item by id.
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | String | true | 元素 ID |
Return
- Type of the return value: Object;
- If there are items that match the rule, return the first one. Return
undefined
otherwise.
Usage
const node = graph.findById('node');
findAll(type, fn)
Find all the items that match the rule.
Parameters
Name | Type | Required | Description |
---|---|---|---|
type | String | true | The type of the item. Options: 'node' , 'edge' . |
fn | Function | true | Rule for searching. |
Return
- Type of the return value: Array;
- If there are items that match the rule, return all of them. Return
undefined
otherwise.
Usage
const nodes = graph.findAll('node', node => {
return node.get('model').x;
});
findAllByState(type, state)
Find all the items whose value of state is true.
Parameters
Name | Type | Required | Description |
---|---|---|---|
type | String | true | The type of the item. Options: 'node' , 'edge' . |
state | String | true | State for searching. |
Return
- Type of the return value: Array;
- Return all the items that match the state.
Usage
// Find all the items whose 'selected' state is true
const nodes = graph.findAllByState('node', 'selected');
Data
save()
Get the graph data.
Return
- Type of the return value: Object;
-
The return value has all the nodes and edges as below:
{ nodes: [], edges: [], groups: [], }
Usage
graph.save();
getNodes()
Get all the node items in the graph.
⚠️Attention: it returns the items but not data models.
Return
- Type of the return value: Array;
- Return the node items in the graph.
Usage
const nodes = graph.getNodes();
getEdges()
Get all the edge items in the graph.
⚠️Attention: it returns the items but not data models.
Return
- Type of the return value: Array;
- Return the edge items in the graph.
Usage
const edges = graph.getEdges();
Coordinate Transformation
In this part, we will describe the methods about transformation between view port, canvas, and client coordinates. The relationships between them are shown below:
getPointByClient(clientX, clientY)
Transform client/screen coordinates into view port coordinates.
Parameters
Name | Type | Required | Description |
---|---|---|---|
clientX | Number | true | x coordinate of client/screen. |
clientY | Number | true | y coordinate of client/screen. |
Return
- Type of the return value: Object;
- Includes x and y.
Usage
const point = graph.getPointByClient(e.clientX, e.clientY);
console.log('The x and y of view port are: ', point.x, point.y);
getClientByPoint(x, y)
Transform view port coordinates into client/screen coordinates.
Parameters
Name | Type | Required | Description |
---|---|---|---|
x | Number | true | x coordinate of view port. |
y | Number | true | y coordinate of view port. |
Return
- Type of the return value: Object;
- Includes
x
andy
.
Usage
const point = graph.getClientByPoint(100, 200);
console.log('The x and y of client/screen are: ', point.x, point.y);
getPointByCanvas(canvasX, canvasY)
Transform canvas coordinates into view port coordinates.
Parameters
Name | Type | Required | Description |
---|---|---|---|
canvasX | Number | true | The x coordinate of canvas. |
canvasY | Number | true | The y coordinate of canvas. |
Return
- Type of the return value: Object;
- Include x and y.
Usage
const point = graph.getPointByCanvas(100, 200);
console.log('The x and y of view port: ', point.x, point.y);
getCanvasByPoint(x, y)
Transform view port coordinates into canvas coordinates.
Parameters
Name | Type | Required | Description |
---|---|---|---|
x | Number | true | The x coordinate of view port. |
y | Number | true | The y coordinate of view port. |
Return
- Type of the return value: Object;
- Includes x and y.
Usage
const point = graph.getCanvasByPoint(100, 200);
console.log('The x and y coordinates of canvas: ', point.x, point.y);
Animation
positionsAnimate()
Update the node positions according to the data model animatively. The animateCfg
of the graph will be the animation configurations.
stopAnimate()
Stop the animation on the canvas.
Usage
graph.stopAnimate();
isAnimating()
Return if the graph is animating.
Others
addPlugin(plugin)
Add plugin to graph.
Parameters
Name | Type | Required | Description |
---|---|---|---|
plugin | Object | true | Instance of the plugin. |
Usage
import miniMap from '@antv/g6/build/minimap';
graph.Plugin(miniMap);
removePlugin(plugin)
Remove the plugin from graph.
Parameters
Name | Type | Required | Description |
---|---|---|---|
plugin | Object | true | The Instance of the plugin. |
Usage
import miniMap from '@antv/g6/build/minimap';
graph.removePlugin(miniMap);
get(key)
Get an property of graph by key.
Parameters
Name | Type | Required | Description |
---|---|---|---|
key | String | true | Key of the property. |
Usage
// get the group
const group = graph.get('group');
// get the canvas instance
const canvas = graph.get('canvas');
// get the value of autoPaint
const autoPaint = graph.get('autoPaint');
set(key, val)
Set the value to an property.
Parameters
Name | Type | Required | Description |
---|---|---|---|
key | String | true | The key of the property. |
val | String / Object / Array | true | The value of the property. |
Usage
// Set capture to false
graph.set('capture', false);
// Set customGroup to group
graph.set('customGroup', group);
// Set nodeIdList to [1, 3, 5]
graph.set('nodeIdList', [1, 3, 5]);
downloadImage(name)
Export the canvas as an image.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | String | true | The name of the image. |
Usage
graph.downloadImage();
toDataURL()
Generate url of a image of the canvas.
Return
- Type of the return value: String;
- The return value is the image url.
Usage
const dataURL = graph.toDataURL();