Element Operations

Overview of Element Operations

The Element operation API in G6 allows you to control the behavior and attributes of elements such as nodes, edges, and Combos in the graph. These APIs can be used for:

1. Element State Management: Set, update, or remove the state of elements
2. Element Display Control: Control the z-index and visibility of elements
3. Element Collapse/Expand: Operate the collapse/expand state of collapsible elements
4. Element Position Operations: Move and align element positions
5. Element Focus: Focus the viewport on specific elements

Through these operations, you can achieve rich interactive effects and visual presentations.

API Reference

Graph.getElementPosition(id)

Get the position of an element.

getElementPosition(id: ID): Point;

Parameters:

Return Value:

• Type: [number, number] | [number, number, number]
• Description: Returns the coordinates of the element

Example:

graph.getElementPosition('node1');

Graph.getElementRenderBounds(id)

Get the rendering bounding box of the element itself and its child nodes in the world coordinate system.

getElementRenderBounds(id: ID): AABB;

Parameters:

Return Value:

• Type: AABB
• Description: Returns the rendering bounding box of the element

Graph.getElementRenderStyle(id)

Get the rendering style of an element.

getElementRenderStyle(id: ID): Record<string, any>;

Parameters:

Return Value:

• Type: Record<string, any>
• Description: Returns the rendering style of the element

Graph.getElementState(id)

Get the state of an element.

getElementState(id: ID): State[];

Parameters:

Return Value:

• Type: State[]
• Description: Returns the state of the element

Graph.getElementType(id)

Get the type of an element.

getElementType(id: ID): string;

Parameters:

Return Value:

• Type: string
• Description: Returns the type of the element

Graph.getElementVisibility(id)

Get the visibility of an element.

getElementVisibility(id: ID): 'visible' | 'hidden';

Parameters:

Return Value:

• Type: ‘visible’ | ‘hidden’
• Description: Returns the visibility of the element

Graph.getElementZIndex(id)

Get the z-index of an element.

getElementZIndex(id: ID): number;

Parameters:

Return Value:

• Type: number
• Description: Returns the z-index of the element

Graph.setElementState(id, state, options)

Set the state of an element, supporting two calling methods:

// Set the state of a single element
setElementState(id: ID, state: State | State[], animation?: boolean): Promise<void>;

// Set the state of multiple elements
setElementState(state: Record<ID, State | State[]>, animation?: boolean): Promise<void>;

Parameters:

Single Element State Setting

| Parameter | Description | Type | Default | Required | | ——— | —————– | ————— | —–– | –––– | — | | id | Element ID to set | string | - | ✓ | | state | State to set | State | State[] | - | ✓ | | animation | Enable animation | boolean | - | |

Batch Element State Setting

| Parameter | Description | Type | Default | Required | | ——— | —————————— | ––––––––––––– | –––– | –––– | — | | state | Mapping of element ID to state | Record<ID, State | State[]> | - | ✓ | | animation | Enable animation | boolean | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the state setting operation is complete

Example:

// Set the state of a single element
await graph.setElementState('node1', 'selected');

// Set the state of multiple elements
await graph.setElementState({
  node1: 'selected',
  node2: 'hover',
  node3: ['selected', 'hover'],
});

Graph.setElementVisibility(id, visibility, animation)

Set the visibility of an element, supporting two calling methods:

// Set the visibility of a single element
setElementVisibility(id: ID, visibility: 'visible' | 'hidden', animation?: boolean): Promise<void>;

// Set the visibility of multiple elements
setElementVisibility(visibility: Record<ID, 'visible' | 'hidden'>, animation?: boolean): Promise<void>;

Parameters:

Single Element Visibility Setting

| Parameter | Description | Type | Default | Required | | ––––– | —————– | ——— | –––– | –––– | — | | id | Element ID to set | string | - | ✓ | | visibility | Visibility to set | ‘visible’ | ‘hidden’ | - | ✓ | | animation | Enable animation | boolean | - | |

Batch Element Visibility Setting

| Parameter | Description | Type | Default | Required | | ––––– | ———————————– | –––––––––– | ——— | –––– | — | | visibility | Mapping of element ID to visibility | Record<ID, ‘visible’ | ‘hidden’> | - | ✓ | | animation | Enable animation | boolean | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the visibility setting operation is complete

Example:

// Set the visibility of a single element
await graph.setElementVisibility('node1', 'hidden');

// Set the visibility of multiple elements
await graph.setElementVisibility({
  node1: 'hidden',
  node2: 'visibility',
});

Graph.setElementZIndex(id, zIndex)

Set the z-index of an element, supporting two calling methods:

// Set the z-index of a single element
setElementZIndex(id: ID, zIndex: number): Promise<void>;

// Set the z-index of multiple elements
setElementZIndex(zIndex: Record<ID, number>): Promise<void>;

Parameters:

Single Element Z-Index Setting

Batch Element Z-Index Setting

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the z-index setting operation is complete

Example:

// Set the z-index of a single element
await graph.setElementZIndex('node1', 10);

// Set the z-index of multiple elements
await graph.setElementZIndex({
  node1: 10,
  node2: 20,
  node3: 30,
});

Graph.setNode(node)

Set the node style mapping, i.e., the value of options.node.

setNode(node: NodeOptions): void;

Parameters:

Example:

// Set the fill color of all nodes to red
graph.setNode({
  style: {
    fill: 'red',
  },
});

Graph.setEdge(edge)

Set the edge style mapping, i.e., the value of options.edge.

setEdge(edge: EdgeOptions): void;

Parameters:

Graph.setCombo(combo)

Set the combo style mapping, i.e., the value of options.combo.

setCombo(combo: ComboOptions): void;

Parameters:

Graph.collapseElement(id, options)

Collapse the specified element, usually used to collapse Combos or nodes with child elements.

collapseElement(id: ID, options?: boolean | CollapseExpandNodeOptions): Promise<void>;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | ————————————————————— | —–– | —————————————————–– | –––– | — | | id | Element ID to collapse | string | - | ✓ | | options | Enable animation or detailed configuration for collapsing nodes | boolean | CollapseExpandNodeOptions | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the collapse operation is complete

Example:

// Simple collapse with default configuration
await graph.collapseElement('combo1');

// Collapse with animation
graph.collapseElement('combo1', true);

// Collapse while ensuring the position of expanded/collapsed nodes remains unchanged
await graph.collapseElement('combo1', {
  align: true,
});

Graph.expandElement(id, options)

Expand the specified element, usually used to expand previously collapsed Combos or nodes.

expandElement(id: ID, options?: boolean | CollapseExpandNodeOptions): Promise<void>;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | ––––––––––––––––––––––––––––––– | —–– | —————————————————–– | –––– | — | | id | Element ID to expand | string | - | ✓ | | options | Enable animation or detailed configuration for expanding nodes | boolean | CollapseExpandNodeOptions | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the expand operation is complete

Example:

// Simple expand with default configuration
await graph.expandElement('combo1');

// Expand with animation
await graph.expandElement('combo1', true);

// Expand while ensuring the position of expanded/collapsed nodes remains unchanged
await graph.expandElement('combo1', {
  align: true,
});

Graph.frontElement(id)

Bring the specified element to the front, making it appear above other overlapping elements.

frontElement(id: ID | ID[]): void;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | ———– | —— | –––– | –––– | — | | id | Element ID | string | string[] | - | ✓ |

Return Value:

• Type: void

Example:

// Bring a node to the front
graph.frontElement('node1');

// Bring multiple selected nodes to the front
graph.frontElement(['node1', 'node2', 'node3']);

Graph.showElement(id, animation)

Show the specified element.

showElement(id: ID | ID[], animation?: boolean): Promise<void>;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | –––––––– | —–– | –––– | –––– | — | | id | Element ID | string | string[] | - | ✓ | | animation | Enable animation | boolean | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the show operation is complete

Example:

// Show a single element
await graph.showElement('node1');

// Show an element with animation
await graph.showElement('node1', true);

// Show multiple elements
await graph.showElement(['node1', 'node2', 'node3']);

Graph.hideElement(id, animation)

Hide the specified element.

hideElement(id: ID | ID[], animation?: boolean): Promise<void>;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | –––––––– | —–– | –––– | –––– | — | | id | Element ID | string | string[] | - | ✓ | | animation | Enable animation | boolean | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the hide operation is complete

Example:

// Hide an element without animation
await graph.hideElement('node1');

// Hide an element with animation
await graph.hideElement('node1', true);

// Hide multiple elements
await graph.hideElement(['node1', 'node2', 'node3'], true);

Graph.translateElementBy(id, offset, animation)

Translate an element by a specified distance, supporting two calling methods:

// Translate an element by a specified distance (relative translation)
translateElement(id: ID, offset: Point, animation?: boolean): Promise<void>;

// Translate multiple elements by a specified distance (relative translation)
translateElement(offsets: Record<ID, Point>, animation?: boolean): Promise<void>;

Parameters:

Single Element Translation

Batch Element Translation

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the translation operation is complete

Example:

// Translate right by 100 pixels and down by 50 pixels
await graph.translateElementBy('node1', [100, 50]);

// Translate with animation
await graph.translateElementBy('node1', [100, 50], true);

// Apply the same translation to multiple nodes
await graph.translateElementBy(
  {
    node1: [50, 50],
    node2: [100, 100],
    node3: [150, 150],
  },
  true,
);

Graph.translateElementTo(id, position, animation)

Move an element to a specified position, supporting two calling methods:

// Move an element to a specified position (absolute position)
translateElementTo(id: ID, position: Point, animation?: boolean): Promise<void>;

// Move multiple elements to specified positions (absolute position)
translateElementTo(positions: Record<ID, Point>, animation?: boolean): Promise<void>;

Parameters:

Single Element Movement

Batch Element Movement

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the movement operation is complete

Example:

// Move a node to position (200, 300) on the canvas
await graph.translateElementTo('node1', [200, 300]);

// Move with animation
await graph.translateElementTo('node1', [200, 300], true);

// Arrange a group of nodes neatly
await graph.translateElementTo(
  {
    node1: [100, 100],
    node2: [200, 200],
    node3: [300, 100],
  },
  true,
);

Graph.focusElement(id, animation)

Focus on the specified element, centering it in the viewport.

focusElement(id: ID | ID[], animation?: ViewportAnimationEffectTiming): Promise<void>;

Parameters:

| Parameter | Description | Type | Default | Required | | ——— | ———————————– | ————————————————————— | –––– | –––– | — | | id | One or more element IDs to focus on | string | string[] | - | ✓ | | animation | Viewport animation configuration | ViewportAnimationEffectTiming | - | |

Return Value:

• Type: Promise
• Description: Returns a Promise that resolves when the focus operation is complete

Example:

// Focus on a single node
await graph.focusElement('node1');

// Use custom animation configuration
await graph.focusElement('node1', {
  duration: 800,
  easing: 'ease-in-out',
});

// Focus on multiple nodes
await graph.focusElement(['node1', 'node2', 'node3']);

Type Definitions

CollapseExpandNodeOptions

Configuration options for collapsing or expanding elements.

interface CollapseExpandNodeOptions {
  /**
   * Enable animation
   */
  animation?: boolean;
  /**
   * Ensure the position of expanded/collapsed nodes remains unchanged
   */
  align?: boolean;
}

ViewportAnimationEffectTiming

Viewport animation configuration type.

type ViewportAnimationEffectTiming =
  | boolean // Enable animation
  | {
      easing?: string; // Easing function
      duration?: number; // Animation duration (ms)
    };

AABB

AABB (Axis-Aligned Bounding Box) is a fundamental concept in computer graphics.

interface AABB {
  x: number; // x-coordinate of the top-left corner of the rectangle
  y: number; // y-coordinate of the top-left corner of the rectangle
  width: number; // Width of the rectangle
  height: number; // Height of the rectangle
}

State

Element state type.

type State = 'selected' | 'hover' | 'active' | 'inactive' | 'disabled' | string;