Node

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.

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

Or

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

addPorts(…)

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

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

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.

hasPort(…)

hasPort(portId: string): boolean

Checks if the specified connection port exists.

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.

getPortAt(…)

getPortAt(index: number): PortMetadata | null

Gets the connection port at the specified index.

getPorts()

getPorts(): PortMetadata[]

Gets all connection ports.

getPortsByGroup(…)

getPortsByGroup(groupName: string): PortMetadata[]

Gets all connection ports under the specified group.

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.

Removes the connection port with the specified ID.

removePortAt(…)

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

Removes the connection port at the specified index.

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.

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.

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.

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.

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

removePortProp(…)

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

Removes the options of the specified port.

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

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

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.