g6/docs/api/Graph.en.md

title	order	redirect_from
Graph	1	/en/docs/api

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 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 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 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 repaint the canvas automatically after updating or deleting items.

Parameters

Name	Type	Required	Description
auto	Boolean	true	Whether 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.

1. If there is type in cfg, type is a String and it is different from current layout method, updateLayout(cfg) will change the layout method and relayout;
2. If there is no type in cfg, 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 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.

<<<<<<< HEAD ⚠️Attention: it returns the items but not data models.

Attention: it returns the items but not data models.

feat: english version of API

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 and y.

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.

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 ant attribute of graph by key.

Parameters

Name	Type	Required	Description
key	String	true	Key of the attribute.

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 attribute.

Parameters

Name	Type	Required	Description
key	String	true	The key of the attribute.
val	String / Object	Array	true

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()