Node | X6

Node is the base class for all nodes, inheriting from Cell, and defines the common properties and methods for nodes.

Attributes

In addition to inheriting from Cell attributes, the following attributes are also supported.

Option	Type	Default Value	Description
size	`{ width: number; height: number }`	`{ width: 1, height: 1 }`	Node size.
position	`{ x: number; y: number }`	-	Node position.
angle	number	-	Node rotation angle.
ports	object	-	Connection ports.
portMarkup	Markup	object	DOM structure of the connection ports.
portLabelMarkup	Markup	object	DOM structure of the connection port labels.

Size

The size of the node, which is an object containing width and height properties, can be retrieved and set using the size(...) method.

Position

The position of the node, which is an object containing x and y properties, can be retrieved and set using the position(...) method.

Angle

The rotation angle of the node, with the rotation center being the center of the node, can be retrieved and set using the rotate(...) method.

Ports

Connection ports are fixed connection points on the node. Many graph applications have connection ports, and some applications also categorize them into input and output ports.

The ports option is a complex object that can be used as follows:

const node = new Node({
  ports: {
    group: { ... }, // Connection port group definition
    items: [ ... ], // Connection ports
  }
})

const node = new Node({
  ports: [ ... ], // Connection ports
})

Typically, we group connection ports with the same behavior and appearance into the same group and set the grouping through the group option, which is an object { [groupName: string]: PortGroupMetadata }, where the group name is the key and the value is the default options for each group of connection ports. The supported options are as follows:

interface PortGroupMetadata {
  /**
   * Connection port DOM structure definition.
   */
  markup?: Markup

  /**
   * Attributes and styles.
   */
  attrs?: Attr.CellAttrs

  /**
   * DOM hierarchy of the connection ports, the higher the value, the higher the hierarchy.
   */
  zIndex?: number | 'auto'

  /**
   * Layout of the connection ports in the group.
   */
  position?:
    | [number, number] // Absolute positioning
    | string // Name of the connection port layout method
    | {
        // Name and parameters of the connection port layout method
        name: string
        args?: object
      }

  /**
   * Connection port label.
   */
  label?: {
    markup?: Markup
    position?: {
      // Layout of the connection port label
      name: string // Layout name
      args?: object // Layout parameters
    }
  }
}

For example:

const node = new Node({
  ports: {
    group: {
      group1: {
        markup: { tagName: 'circle' },
        attrs: { },
        zIndex: 1,
        position: {
          name: 'top',
          args: {},
        },
      },
      group2: { ... },
      group3: { ... },
    },
    items: [ ... ],
  }
})

Another option, items, is an array PortMetadata[], where each item represents a connection port. The supported options for connection ports are as follows:

interface PortMetadata {
  /**
   * Unique ID of the connection port, automatically generated by default.
   */
  id?: string

  /**
   * Group name, specifying a group will inherit the connection port options from the group.
   */
  group?: string

  /**
   * Provides parameters for the layout algorithm specified in the group for the designated connection port.
   * We cannot specify a layout algorithm for a single connection port, but we can provide different parameters for the layout algorithm specified in the group.
   */
  args?: object

  /**
   * DOM element and structure definition of the connection port. Specifying this option will override the default options provided by the group.
   */
  markup?: Markup

  /**
   * Element attribute styles. Specifying this option will override the default options provided by the group.
   */
  attrs?: Attr.CellAttrs

  /**
   * DOM hierarchy of the connection port, the higher the value, the higher the hierarchy. Specifying this option will override the default options provided by the group.
   */
  zIndex?: number | 'auto'

  /**
   * Connection port label. Specifying this option will override the default options provided by the group.
   */
  label?: {
    markup?: Markup
    position?: {
      // Layout of the connection port label
      name: string // Layout name
      args?: object // Layout parameters
    }
  }
}

For example:

const node = new Node({
  ports: {
    group: { ... },
    items: [
      { id: 'port1', group: 'group1', ... },
      { id: 'port2', group: 'group1', ... },
      { id: 'port3', group: 'group2', ... },
    ],
  }
})

For more details, please refer to the Configure Connection Ports documentation.

Port Markup

The DOM structure of the connection ports. When neither ports.groups nor ports.items specifies markup for the corresponding connection port, this default option is used to render the connection port, with the default value being:

{
  tagName: 'circle',
  selector: 'circle',
  attrs: {
    r: 10,
    fill: '#fff',
    stroke: '#000',
  },
}

This indicates that the connection port is rendered as a circle with a radius of 10px.

Port Label Markup

The DOM structure of the connection port labels. When neither ports.groups nor ports.items specifies markup for the corresponding connection port label, this default option is used to render the connection port label, with the default value being:

{
  tagName: 'text',
  selector: 'text',
  attrs: {
    fill: '#000000',
  },
}

Methods

General

isNode()

isNode(): true

Determines if it is a node; this method always returns true.

getBBox(...)

getBBox(options: { deep?: boolean }): Rectangle

Gets the bounding box of the node.

Name	Type	Required	Default Value	Description
options.deep	boolean		`false`	When `true`, includes the bounding box of all child nodes and edges; defaults to `false`.

const rect1 = node.getBBox()
const rect2 = node.getBBox({ deep: true })

Size

size(...)

/**
 * Gets the size of the node.
 */
size(): Size

/**
 * Sets the size of the node.
 */
size(size: Size, options?: Node.ResizeOptions): this

/**
 * Sets the size of the node.
 */
size(width: number, height: number, options?: Node.ResizeOptions): this

Gets the size of the node.

const size = node.size()
console.log(size.width, size.height)

The parameters and usage for setting the node size are the same as the resize method.

resize(...)

Changes the size of the node. Depending on the rotation angle and options.direction, both the position and size of the node may change.

Name	Type	Default Value	Description
width	number		Node width.
height	number		Node height.
options.direction	Direction	`'bottom-right'`	The direction in which to change the size; defaults to fixing the top-left corner and resizing towards the bottom-right.
options.silent	boolean	`false`	When `true`, does not trigger `'change:size'` and `'change:position'` events and does not redraw the canvas.
options...others	object		Other custom key-value pairs that can be used in event callbacks.

Supports resizing the node in 8 directions, with the default being 'bottom-right', which means fixing the top-left corner and resizing towards the bottom-right.

top
right
bottom
left
top-left
top-right
bottom-left
bottom-right

node.resize(100, 40)

// Fixing the bottom-right corner, resizing towards the top-left
node.resize(100, 40, { direction: 'top-left' })

// Do not trigger events and redraw
node.resize(100, 40, { silent: true })

scale(...)

scale(
  sx: number,
  sy: number,
  origin?: Point.PointLike,
  options?: Node.SetOptions,
): this

Scales the node. Depending on the scaling center and scaling ratio, both the size and position of the node may change.

Name	Type	Required	Default Value	Description
sx	number	✓		Scaling ratio in the X direction.
sy	number	✓		Scaling ratio in the Y direction.
origin	Point.PointLike \| null		-	Scaling center, defaults to the center of the node.
options.silent	boolean		`false`	When `true`, does not trigger `'change:size'` and `'change:position'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

node.scale(1.5, 1.5)

// Custom scaling center
node.scale(1.5, 1.5, { x: 100, y: 30 })

// Do not trigger events and redraw
node.scale(1.5, 1.5, null, { silent: true })

fit(...)

fit(options?: Node.FitEmbedsOptions): this

Automatically adjusts the size and position of the node based on the size and position of child nodes and edges, ensuring that all child nodes and edges are within the bounding box of the node.

Name	Type	Default Value	Description
options.padding	number \| `{ top: number; right: number; bottom: number; left: number }`	`0`	Padding.
options.deep	boolean	`false`	Whether to include all descendant nodes and edges; defaults to only including direct child nodes and edges.
options.silent	boolean	`false`	When `true`, does not trigger events and redraw the canvas.
options...others	object		Other custom key-value pairs that can be used in event callbacks.

node.fit()
node.fit({ padding: 10 })
node.fit({ padding: { top: 20, bottom: 20, left: 10, right: 10 } })

Position

position(...)

/**
 * Gets the position of the node.
 */
position(options?: Node.GetPositionOptions): Point.PointLike

/**
 * Sets the position of the node.
 */
position(x: number, y: number, options?: Node.SetPositionOptions): this

Gets the position of the node.

Name	Type	Required	Default Value	Description
options.relative	boolean		`false`	Whether to return the relative position to the parent node; defaults to `false`, indicating that the absolute position relative to the canvas is returned.

const pos = rect.position()
console.log(pos.x, pos.y)

const relativePos = child.position({ relative: true })
console.log(relativePos.x, relativePos.y)

Sets the position of the node.

Name	Type	Required	Default Value	Description
x	number	✓		Absolute or relative X-axis coordinate of the node.
y	number	✓		Absolute or relative Y-axis coordinate of the node.
options.relative	boolean		`false`	Whether the provided coordinates are relative coordinates. When `true`, indicates that the provided coordinates are relative to the parent node; defaults to `false`, indicating that the provided coordinates are absolute coordinates relative to the canvas.
options.deep	boolean		`false`	Whether to also change the position of child nodes/edges.
options.silent	boolean		`false`	When `true`, does not trigger `'change:position'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

By default, absolute coordinates are used. When options.relative is true, relative coordinates are used.

// Move the node to the canvas position [30, 30]
node.position(30, 30)

// Move the child node to the relative position [30, 30] at the top-left corner of the parent node
child.position(30, 30, { relative: true })

When options.deep is true, child nodes and edges will also be moved simultaneously.

parent.position(30, 30, { deep: true })

When options.silent is true, it does not trigger 'change:position' events and does not redraw the canvas.

node.position(30, 30, { silent: true })

Other custom key-value pairs can be used in event callbacks.

node.position(30, 30, { otherKey: 'otherValue', ... })

translate(...)

translate(tx?: number, ty?: number, options?: Node.TranslateOptions): this

Translates the node along with its child nodes and edges.

Name	Type	Default Value	Description
tx	number	`0`	The offset of the node in the X direction.
ty	number	`0`	The offset of the node in the Y direction.
options.restrict	Rectangle.RectangleLike	`undefined`	Restricts the movable range of the node to the specified rectangular area.
options.transition	boolean \| Animation.Options	`false`	Whether to use animation or specify an animation option.
options.silent	boolean	`false`	When `true`, does not trigger `'change:position'` events and does not redraw the canvas.
options...others	object		Other custom key-value pairs that can be used in event callbacks.

When the specified tx and ty are undefined, it indicates that the corresponding direction's translation amount is 0.

node.translate(30, 30)
node.translate(30) // Move only in the X direction
node.translate(undefined, 30) // Move only in the Y direction

We can restrict the movement of the node within a specified rectangle {x: number; y: number; width: number; height: number} using the options.restrict option.

For example, we can restrict the movement of child nodes within the bounding box of the parent node:

child.translate(30, 30, {
  restrict: child.getParent().getBBox(),
})

When options.transition is true or an animation option is specified, it indicates that animation should be used to translate the node. For more details, please refer to the Using Animation Documentation.

// Translate the node using the default animation
node.translate(30, 30, {
  transition: true,
})

// Custom animation options
node.translate(30, 30, {
  transition: {
    duration: 2000,
  },
})

When options.silent is true, it does not trigger 'change:position' events and does not redraw the canvas.

node.translate(30, 30, { silent: true })

Other custom key-value pairs can be used in event callbacks.

node.translate(30, 30, { otherKey: 'otherValue', ... })

Rotation Angle

getAngle()

getAngle(): number

Gets the rotation angle of the node.

if (node.getAngle() !== 0) {
  // do something
}

rotate(...)

rotate(
  deg: number,
  absolute?: boolean,
  origin?: Point.PointLike,
  options?: Node.RotateOptions,
): this

Rotates the node.

Name	Type	Required	Default Value	Description
deg	number	✓		Rotation degree.
options.absolute	boolean		`false`	When `true`, indicates that the given degree is the absolute degree after rotation; defaults to `false`, indicating that the node rotates the given degree based on the current rotation angle.
options.center	Point.PointLike		`undefined`	Defaults to rotating around the center of the node; when `options.center` is given, it indicates rotating around the specified center.
options.silent	boolean		`false`	When `true`, does not trigger `'change:angle'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

By default, it is a relative rotation, meaning that the node rotates the given degree based on the current rotation angle. When options.absolute is true, it indicates absolute rotation, meaning that the given degree is the angle of the node after rotation.

// Relative rotation, the node rotates 30 degrees based on the current rotation angle
node.rotate(30)

// Absolute rotation, the angle of the node after rotation is 30 degrees
node.rotate(30, { absolute: true })

By default, it rotates around the center of the node. You can specify a rotation center using the options.center option.

node.rotate(30, { center: { x: 10, y: 10 } })

By default, it triggers 'change:angle' events and redraws the canvas. When options.silent is true, it does not trigger 'change:angle' events and does not redraw the canvas.

node.rotate(30, { silent: true })

Other custom key-value pairs can be used in event callbacks.

node.rotate(30, { otherKey: 'otherValue', ... })

Connection Ports

Connection ports are fixed connection points on the node. Many graph applications have connection ports, and some applications also categorize them into input and output ports.

In the above, we introduced the data structure of connection ports. Here, we will continue to introduce some methods for operating connection ports on the node.

addPort(...)

addPort(port: PortMetadata, options?: Node.SetOptions): this

Adds a single connection port. The connection port is added to the end of the connection port array.

Name	Type	Required	Default Value	Description
port	PortMetadata	✓		Connection port.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

addPorts(...)

addPorts(ports: PortMetadata[], options?: Node.SetOptions)

Adds multiple connection ports. The connection ports are added to the end of the connection port array.

Name	Type	Required	Default Value	Description
port	PortMetadata[]	✓		Array of connection ports.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

insertPort(...)

insertPort(index: number, port: PortMetadata, options?: Node.SetOptions): this

Adds a connection port at the specified position. Note that the port parameter needs to include the id property.

Name	Type	Required	Default Value	Description
index	number	✓		Position of the connection port.
port	PortMetadata	✓		Connection port.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

hasPort(...)

hasPort(portId: string): boolean

Checks if the specified connection port exists.

Name	Type	Required	Default Value	Description
portId	string	✓		Connection port ID.

if (node.hasPort('port1')) {
  // do something
}

hasPorts()

hasPorts(): boolean

Checks if the node contains connection ports.

if (node.hasPorts()) {
  // do something
}

getPort(...)

getPort(portId: string): PortMetadata

Gets the connection port by ID.

Name	Type	Required	Default Value	Description
portId	string	✓		Connection port ID.

getPortAt(...)

getPortAt(index: number): PortMetadata | null

Gets the connection port at the specified index.

Name	Type	Required	Default Value	Description
index	number	✓		Connection port index.

getPorts()

getPorts(): PortMetadata[]

Gets all connection ports.

getPortsByGroup(...)

getPortsByGroup(groupName: string): PortMetadata[]

Gets all connection ports under the specified group.

Name	Type	Required	Default Value	Description
groupName	string	✓		Group name.

removePort(...)

/**
 * Removes the specified connection port.
 */
removePort(port: PortMetadata, options?: Node.SetOptions): this

/**
 * Removes the connection port with the specified ID.
 */
removePort(portId: string, options?: Node.SetOptions): this

Removes the specified connection port.

Name	Type	Required	Default Value	Description
port	PortMetadata	✓		Connection port.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

Removes the connection port with the specified ID.

Name	Type	Required	Default Value	Description
portId	string	✓		Connection port ID.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

removePortAt(...)

removePortAt(index: number, options?: Node.SetOptions): this

Removes the connection port at the specified index.

Name	Type	Required	Default Value	Description
index	number	✓		Connection port index.
options.silent	boolean		`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

removePorts(...)

/**
 * Removes all connection ports.
 */
removePorts(options?: Node.SetOptions): this

/**
 * Removes the specified connection ports.
 */
removePorts(ports: (PortMetadata | string)[], options?: Node.SetOptions): this

Removes the specified multiple connection ports.

Name	Type	Default Value	Description
ports	(PortMetadata \| string)[]		Array of connection ports to be removed.
options.silent	boolean	`false`	When `true`, does not trigger `'change:ports'` events and does not redraw the canvas.
options...others	object		Other custom key-value pairs that can be used in event callbacks.

getPortIndex(...)

getPortIndex(port: PortMetadata | string): number

Obtain the index position of the connection port.

getPortProp(...)

getPortProp<T>(portId: string, path?: string | string[]): any

Retrieves the property value at the specified path of the port. When the path is empty, it returns the complete port.

Name	Type	Required	Default Value	Description
portId	string	✓		Port ID.
path	string \| string[]			Property path. When `path` is of type `string`, the path is a string separated by `'/'`. When `path` is of type `string[]`, the path is an array of keys that make up the port object path.

node.getPortProp('port1')
node.getPortProp('port1', 'attrs/circle')
node.getPortProp('port1', ['attrs', 'circle'])

setPortProp(...)

setPortProp(
  portId: string,
  path: string | string[],
  value: any,
  options?: Node.SetOptions,
): this

Sets the property of the port based on the path.

Name	Type	Required	Default Value	Description
portId	string	✓		Port ID.
path	string \| string[]	✓		Property path. When `path` is of type `string`, the path is a string separated by `'/'`. When `path` is of type `string[]`, the path is an array of keys that make up the port object path.
value	any	✓		Property value.
options.silent	boolean		`false`	If `true`, does not trigger the `'change:ports'` event and canvas redraw.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

node.setPortProp('port1', 'attrs/circle', {
  fill: '#ffffff',
  stroke: '#000000',
})
node.setPortProp('port1', ['attrs', 'circle'], {
  fill: '#ffffff',
  stroke: '#000000',
})

setPortProp(
  portId: string,
  value: DeepPartial<PortMetadata>,
  options?: Node.SetOptions,
): this

Sets the properties of the port, merging the provided property options with the current values using deep merge.

Name	Type	Required	Default Value	Description
portId	string	✓		Port ID.
value	DeepPartial<PortMetadata>	✓		Port options.
options.silent	boolean		`false`	If `true`, does not trigger the `'change:ports'` event and canvas redraw.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

node.getPortProp('port1', {
  attrs: {
    circle: {
      fill: '#ffffff',
      stroke: '#000000',
    },
  },
})

removePortProp(...)

removePortProp(portId: string, options?: Node.SetOptions): this

Removes the options of the specified port.

Name	Type	Required	Default Value	Description
portId	string	✓		Port ID.
options.silent	boolean		`false`	If `true`, does not trigger the `'change:ports'` event and canvas redraw.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

removePortProp(portId: string, path: string | string[], options?: Node.SetOptions): this

Removes the options of the specified port at the specified path.

Name	Type	Required	Default Value	Description
portId	string	✓		Port ID.
path	string \| string[]	✓		Property path. When `path` is of type `string`, the path is a string separated by `'/'`. When `path` is of type `string[]`, the path is an array of keys that make up the port object path.
options.silent	boolean		`false`	If `true`, does not trigger the `'change:ports'` event and canvas redraw.
options...others	object			Other custom key-value pairs that can be used in event callbacks.

portProp(...)

portProp(portId: string): PortMetadata
portProp<T>(portId: string, path: string | string[]): T
portProp(
  portId: string,
  path: string | string[],
  value: any,
  options?: Node.SetOptions,
): this
portProp(
  portId: string,
  value: DeepPartial<PortMetadata>,
  options?: Node.SetOptions,
): this

This method is a combination of getPortProp and setPortProp, with parameter options and usage consistent with these two methods.