Install

$ npm install @antv/graphin --save

First Example

Here is a simple example to show the usage of Graphin. You can use https://codesandbox.io/s/data-driven-fkue0 as a starter and fork a new Code Sandbox to play around.

01. Rendering data

There is no difference between Graphin and typical React component. It has a required props data which will be checked internally. There are some requirements for props.data. For details, see: Main Concepts/Data.

Graphin provides a mock function to help us generate some graph data quickly, let us have a try:

import React from 'react';
import ReactDOM from 'react-dom';
import Graphin, { Utils } from '@antv/graphin';

import "@antv/graphin/dist/index.css"; // import css fro graphin
import './styles.css';

const App = () => {
    const data = Utils.mock(10).graphin();
    return (
        <div className="App">
            <Graphin data={data} />
        </div>
    );
};

const rootElement = document.getElementById('root');
ReactDOM.render(<App />, rootElement);

You can preview this in the Code Sanbox link above.

02. Using layout

There are 6 built-in layouts in Grapnin, and the default is concentric (concentric layout). We can switch the default layout according to our needs.

For example, if we want nodes to be arranged in a force layout:

-  <Graphin data={data} />
+  <Graphin data={data} layout={{name:"layout"}}/>

Preview:

03. Using components

Graphin provides two official components, Toolbar and ContextMenu. You can get more detail about them in the Main-concepts/Components.

We take Toolbar as an example:

• Install graphin components. Analysis components of graphin are published as package @antv/graphin-components.

$ npm install @antv/graphin-components --save

• Place Toolbar component inside Graphin component so that Graphin can pass internal properties such as graph, apis, etc. to the Toolbar:

import React from 'react';
import ReactDOM from 'react-dom';
import Graphin, { Utils } from '@antv/graphin';
import { Toolbar } from '@antv/graphin-components';

import "@antv/graphin/dist/index.css"; // Graphin CSS
import "@antv/graphin-components/dist/index.css"; // Graphin Component CSS
import './styles.css';

const App = () => {
    const data = Utils.mock(10).circle().graphin();
    return (
        <div className="App">
            <Graphin data={data} layout={{ name: 'concentric' }}>
                <Toolbar />
            </Graphin>
        </div>
    );
};

const rootElement = document.getElementById('root');
ReactDOM.render(<App />, rootElement);

Preview:

We can play around these features of graphin component in the Grapin Studio:

• undo/redo
• zoomIn/out
• fullscreen
• contextmenu

04. Listening event

There are a lot of events in graph analysis. If we want to listen events, we should:

• 1. Get ref of graphin instance
• 2. Use the G6 instance on graphin instance to listen events

const App = () => {
    const data = Utils.mock(10).graphin();
    const graphRef = React.createRef(null);
    React.useEffect(() => {
        const { graph } = graphRef.current;
        graph.on('node:click', e => {
            console.log('node:click', e);
        });
    }, []);
    return (
        <div className="App">
            <Graphin data={data} layout={{ name: 'concentric' }} ref={graphRef}>
                <Toolbar />
            </Graphin>
        </div>
    );
};

05. Summary and guidance

Through the above 4 steps, we have a knowledge of all four core concepts of Graphin: data, layout, components, and events.

more features

Through the above, we can know that design of Graphin fully complies with React's programming model and completes the mapping from data to view declaratively. Now let's develop two interesting features together, layout switch and node spread.

01. Switching layout

The change of layout will lead to different layout effects to meet people's analytical needs with the same data.

Graphin is a React component, the change of props.layout will lead to diffrent layout effect, so we need to combine layouts and change props.layout every time.

• 1. Interface of LayoutSelector component

interface Layout {
    name: string;
    options: {
        [key: string]: any;
    };
}
interface LayoutSelectorProps {
    /** all built-in layouts**/
    layouts: Layout[];
    /** current layout **/
    value: Layout;
    /** events of switching layout **/
    onChange: (vale: Layout) => void;
}

<LayoutSelector layouts={layouts} value={currentLayout} onChange={handleChange} />;

• 2. How to get Built-in layout information

Graphin provides a number of APIs to the user which are some internal states or functions. Built-in layout information is also available via apis.getInfo().layouts.

• 3. How to get API?

Graphin provides two ways to get the apis interface. The first is to pass the component's props, that is, all the components wrapped inside the Graphin component will get the apis property. The second way is through the ref instance, see Advanced Guide/GraphRef. The first one is suitable for user-defined components, so it is very convenient to get the required interface. The second way is more flexible, and you can use the information provided by Graphin in the outer layer of Graphin, which is often used in complex scenes.

• 4. The complete code is as follows:

02.Node Diffusion

Spreading a node out of its one-degree, second-degree, and multi-degree relationship is a very common analytical technique.

Node Diffusion" is a typical function in graph analysis. Under normal circumstances, node operations in the canvas, such as adding nodes, deleting nodes, we will consider many problems, such as changing from 1 node to 10 nodes, how does the canvas change? Where will the new 9 nodes be placed? When using Graphin, we don't need to think about it. Just remember that it is data-driven. We don't need to care about the internal implementation. Just tell Graphin what data you need to render. Adding nodes does not use graph.add(node), deleting nodes does not need to call graph.remove(node), everything is changed data props.data.

• 1. Perform a data mock on the selected node.
• 2. The Click event triggers a change to state.data.

import React from 'react';
import ReactDOM from 'react-dom';
import Graphin, { Utils } from '@antv/graphin';
import { Toolbar } from '@antv/graphin-components';

const App = () => {
    const [state, setState] = React.useState({
        selected: [],
        data: Utils.mock(10).graphin(),
    });

    const { data, selected } = state;
    const graphRef = React.createRef(null);
    React.useEffect(() => {
        const { graph } = graphRef.current;
        const onNodeClick = e => {
            console.log('node:click', e);
            setState({
                ...state,
                selected: [e.item.get('model')],
            });
        };
        graph.on('node:click', onNodeClick);
        return () => {
            graph.off('node:click', onNodeClick);
        };
    }, [state]);

    const onExpand = () => {
        const count = Math.round(Math.random() * 40);
        const expandData = Utils.mock(count)
            .expand(startNodes)
            .graphin();
        setState({
            ...state,
            data: {
                nodes: [...state.nodes, expandData.nodes],
                edges: [...state.edges, expandData.edges],
            },
        });
    };
    return (
        <div className="App">
            <button onClick={onExpand}>Node Expand</button>
            <Graphin data={data} layout={{ name: 'concentric' }} ref={graphRef}>
                <Toolbar />
            </Graphin>
        </div>
    );
};

• 4. The complete code is as follows:

03. Summary and guidance

These are the quick start guides for Graphin. I believe you have seen the ease of use of Graphin. In fact, there are a lot of ideas about the use of Graphin. For example, what happens when the layout and data change together? You can have a try. if you want to get a deeper understanding of Graphin, you can continue to read the contents of main-concepts and advanced guides.