@ant-design/graphs is a React component library meticulously built on G6. Its purpose is to provide developers with a collection of ready-to-use encapsulated "One Graph, One Action" components, while maintaining compatibility with G6 capabilities. This approach simplifies and streamlines the integration of relational graphs, making the process more efficient.

Understanding "One Graph, One Action"

• "One Graph" refers to graph components tailored for specific business scenarios (e.g., mind maps, organizational charts, flowcharts).
• "One Action" emphasizes the plug-and-play nature of these components. Users can directly select the appropriate graph component for their business needs and customize it with simple configurations.

For highly complex scenarios requiring deep customization, direct development using G6 is recommended to fully utilize its robust and flexible core functionalities.

Terminology

Before delving into the usage of relational graphs, the following terms need to be understood:

• Graph: The central entry point for visualizations, consisting of nodes (representing entities) and edges (representing relationships between entities) that form a complex network structure.
• Data: The core of a graph. Its visualization and interactions are data-driven.
• Element: The basic building blocks of a graph, including nodes (Node), edges (Edge), and combinations (Combo).
• Layout: The arrangement of elements within a graph based on specified rules.
• Behavior: A set of interactions between users and the canvas or elements, such as dragging, zooming, panning, and selecting.
• Plugin: Extensions that enhance functionality, such as attaching additional graphical components or implementing undo-redo mechanisms.
• Transform: Data transformations that process input data for rendering purposes, ensuring input data remains unaltered.

General Graph Properties

Tips: The following properties are common across Graphs components. Unsupported components will be explicitly noted.

Container Properties

Canvas Properties

Lifecycle Properties

Defines callbacks that execute at specific stages of the graph's lifecycle.

Behaviors

Behaviors refer to a series of actions users can take on the canvas and elements, such as dragging, zooming, panning, and selecting. These interactions enhance the intuitiveness of extracting information from the graph.

Type Definition: BehaviorOptions[] | ((existingBehaviors: BehaviorOptions[]) => BehaviorOptions[])

By default, the zoom-canvas (zoom canvas) and drag-canvas (drag canvas) interactions are enabled. For additional interactions, extra configuration is required.

Behaviors can be defined as either a static array or a dynamic function:

• Static Array: Declare all required interactions directly.
• (👍 Recommended) Dynamic Function: Dynamically add or adjust interactions based on existing behaviors.

import { MindMap } from '@ant-design/graphs';

export default () => {
  // Static array example
  const behaviors = ['zoom-canvas', { type: 'drag-canvas', direction: 'x' }];

  // Dynamic function example
  const dynamicBehaviors = (existingBehaviors) => {
    // console.log(existingBehaviors); 👉 [{ key: 'zoom-canvas', type: 'zoom-canvas' }, { key: 'drag-canvas', type: 'drag-canvas' }]
    return [...existingBehaviors, { type: 'click-select' /* properties */ }];
  };

  return <MindMap behaviors={behaviors /** or dynamicBehaviors **/} />;
};

Supports all interactions provided by G6. Below is a brief overview of some built-in interactions, with more details available in G6 - Core Concepts - Interactions:

• Brush Select: Box selection
• Click Element: Click to select
• Collapse Expand: Expand/Collapse
• Create Edge: Create edge
• Drag Canvas: Drag canvas
• Drag Element: Drag element
• Focus Element: Focus element
• Hover Element: Hover over element
• Lasso Select: Lasso selection
• Zoom Canvas: Zoom canvas

If the built-in interactions do not meet specific needs, custom interactions can be created following the tutorial on G6 - Custom Interactions.

Additionally, Graphs also provides a set of interaction extensions.

HoverActivateChain

Purpose: When the user hovers over a node or edge, this interaction highlights the hovered node or edge and its directly connected links (upstream and downstream paths). It is commonly used to emphasize paths in network structures, aiding users in quickly analyzing link relationships.

Configuration: Same as G6 - Behavior - HoverActivate.

HoverActivateNeighbors

Purpose: When hovering over an element, this interaction highlights directly adjacent elements, helping users quickly understand the local context of the element.

Configuration: Same as G6 - Behavior - HoverActivate.

Data Transforms

Data processing (Transforms) is used to manipulate the input data provided by the user. These transformations only affect the data as rendered and do not alter the original input data.

Type Definition: TransformOptions[] | (existingTransforms: TransformOptions[]) => TransformOptions[]

Transforms can be defined in two ways:

• Static array: explicitly specify all required transformers.
• (👍 Recommended) Dynamic function: dynamically generate a new array of transformers based on the existing array.

import { MindMap } from '@ant-design/graphs';

export default () => {
  // Static array approach
  const transforms = [
    { type: 'assign-color-by-branch' /* properties */ },
    { type: 'map-edge-line-width' /* properties */ },
  ];

  // Dynamic function approach
  const dynamicTransforms = (existingTransforms) => {
    return [...existingTransforms, { type: 'arrange-edge-z-index' /* properties */ }];
  };

  return <MindMap transforms={transforms /** or dynamicTransforms **/} />;
};

All data transforms provided by G6 are supported. For a list of built-in transforms, please refer to G6 - API - Data Transform.

Additionally, Graphs also provide various data processing options.

TranslateReactNodeOrigin

Purpose: Since the default origin of React nodes is at the top-left corner, which may not align with the expected layout, this transformation moves the origin to the center of the node using offset values dx and dy.

CollapseExpandReactNode

Purpose: Implements the ability to collapse and expand child nodes of React nodes. This functionality is only valid for React node types. The collapse/expand behavior is controlled by associating side effects with the node.

Configuration:

AssignColorByBranch

Purpose: Assigns colors to branches within a tree diagram to enhance visual distinction within logical branches or hierarchical structures.

Configuration:

ArrangeEdgeZIndex

Purpose: Adjusts the z-index of edges to optimize layer rendering, preventing edges from being obscured or unclear. Commonly used in tree diagrams alongside assign-color-by-branch.

MapEdgeLineWidth

Purpose: Dynamically adjusts the width of edges based on their attributes (such as weight), making the graph more intuitive.

Configuration:

Plugins

Plugins are used to manage the rendering logic of the canvas and additional component rendering, such as embedding graphic components or enabling undo/redo features on the canvas.

Type Definition: PluginOptions[] | ((existingPlugins: PluginOptions[]) => PluginOptions[])

Plugins can be defined as either a static array or a dynamic function:

• Static array: explicitly list the required plugins.
• (👍 Recommended) Dynamic function: dynamically adjust the plugin list based on existing plugins.

import { MindMap } from '@ant-design/graphs';

export default () => {
  // Static array approach
  const plugins = [{ type: 'minimap' /* properties */ }];

  // Dynamic function approach
  const dynamicTransforms = (existingPlugins) => {
    // console.log(existingPlugins); 👉 []
    return [...existingPlugins, { type: 'minimap' /* properties */ }];
  };

  return <MindMap plugins={plugins /** or dynamicPlugins **/} />;
};

All built-in plugins from G6 are supported. For a list of plugins, refer to G6 - API - Plugins.