快速上手
安装
$ npm install @antv/graphin --save
第一个例子
这是一个最简单的 Graphin 组件的在线演示。访问 https://codesandbox.io/s/data-driven-fkue0 创建一个 CodeSandbox 的在线示例,别忘了保存以创建一个新的实例。通过 CodeSandbox,我们可以不用去配那些琐碎的 React 脚手架,快速尝鲜。
01. 渲染数据
Graphin 使用起来就像普通的组件一样,它只有一个必选属性 data
,内部会对其进行数据校验,data 的数据结构有一定的要求,详情参考:核心概念/Data 数据驱动。
Graphin 提供一个 Mock 函数,帮助我们快速生成一些图数据,让我们试试看吧:
import React from 'react';
import ReactDOM from 'react-dom';
import Graphin, { Utils } from '@antv/graphin';
import "@antv/graphin/dist/index.css"; // 引入Graphin CSS
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);
这个例子的效果可以看上一节中的 Sandbox 例子。
02. 使用布局
Graphin 组件内置了 6 种布局,默认提供布局为 concentric(同心圆布局)。我们可以根据自己业务的不同来调整布局。比如,我们希望节点按照里力导(force)排列。让我们来调整上述的代码:
- <Graphin data={data} />
+ <Graphin data={data} layout={{name:"force"}}/>
效果如下:
03. 配置 Node 和 Edge 样式
想要修改 Graphin 的节点和边的样式,我们可以直接修改 data 上的数据:
data.node
和 data.edge
上的各个属性,比如 shape
和 style
等等和 G6 节点和边数据上的是一样的。这里会透传给 G6。这里的配置可以参考 G6 的文档:内置节点 和 内置边。
需要注意的是,如果传入的数据没有 shape,Graphin 给节点的默认 shape 是内置的自定义的 CircleShape。默认的边是内置的自定义 LineEdge。
### 04. 使用组件
Graphin 目前仅提供两个官方组件,Toolbar 和 ContextMenu。关于它们,你们可以在核心概念/Components 分析组件中得到更详细的介绍,我们以添加组件 Toolbar
为例:
- 安装组件,graphin 分析组件发布在单独的 NPM 包 graphin-components 中:
$ npm install @antv/graphin-components —save
- 将组件放在 Graphin 组件内部,这样Graphin-components 基于 antd 组件,因此如果是非 antd 项目,需要手动引入 antd 的 css
Graphin
组件可以将 graph
,apis
等属性传递给分析组件:
效果如下: 关于 Graphin 组件,我们可以到 Grapin Studio 中去体验一下功能: - todo/redo 撤销重做功能 - zoomIn/out 缩小放大功能 - fullscreen 全屏功能 - contextmenu 右键菜单 ### 04. 事件监听 图分析有着非常丰富的事件,如果我们想监听事件,该如何做呢? - - 得到 Graphin 的 Ref 实例 - - 使用 G6 的 graph 进行事件监听 代码如下:
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 组件 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);
### 05. 总结与引导 通过上面的 4 步,我们基本了解了 Graphin 的全部 4 个核心概念 data(数据)、layout(布局)、components(分析组件),events(数据)。 ## 开发点有趣的功能 通过上文,聪明的小伙伴已经发现了,Graphin 的设计完全遵照了 React 的编程模型,声明式的完成了从数据到视图的映射。现在让我们一起来开发两个有趣的功能,布局切换 与 节点扩散。 ### 01. 布局切换
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>
);
};
因为 Graphin 是 React 组件,改变同一组数据,改变布局算法会产生不一样的布局效果,从而满足人们的分析需求。
props.layout
就能改变视图的布局效果,因此我们只要把多种布局 layouts 组合起来,每次切换改变 props.layout
即可。
-
- 设计布局切换 LayoutSelector
组件的接口。
- - 获取 Graphin 支持的内置布局列表
interface Layout {
name: string;
options: {
[key: string]: any;
};
}
interface LayoutSelectorProps {
/ 所有的内置布局/
layouts: Layout[];
/ 当前的布局 /
value: Layout;
/ 切换布局的事件 /
onChange: (vale: Layout) => void;
}
<LayoutSelector layouts={layouts} value={currentLayout} onChange={handleChange} />;
layouts
。
Graphin 提供了很多 API,用于将内部的一些状态或者函数封装给用户使用。内置的布局信息可通过注入到 Graphin 子组件 props 中的 props.apis.getInfo().layouts
获得
- - 完整代码如下:Graphin 提供两种方式获得 apis 接口,第一种是通过组件的 props 传递,即所有包裹在 Graphin 组件内部的组件,都会获得
apis
这个属性。第二种方式是通过ref
实例,详见进阶指导/GraphRef。第一种适用于用户自定义组件,非常方便拿到需要的接口。第二种方式更加灵活,可以在 Graphin 外层使用 Graphin 所提供的信息,常用于复杂场景或者多画布实例的情况下。
02. 节点扩散
将一个节点扩散出它的一度,二度,多度关系,这是非常常用的一种分析手法。
「节点扩散」在图分析中是一个比较典型的功能。常规情况下,在画布中进行节点操作,比如添加节点,删除节点,我们都会考虑很多问题,比如从 1 个节点变为 10 个节点,画布如何变化呢?新增的 9 个节点会放在什么位置呢?使用 Graphin 时,我们就不需要考虑这么多,只需要记住它是数据驱动的,我们不需要关心具体的实现,只需要告诉 Graphin 你需要渲染的数据是什么就可以。增加节点不用使用 graph.add(node)
,删除节点也不用调用 graph.remove(node)
,一切都是改变数据 props.data
即可。
步骤:
- 对选中的节点进行数据 Mock,模拟出节点扩散的结果(实际应用中这可能是从服务端返回的数据)。
- Click 事件触发改变
state.data
即可。
- Click 事件触发改变
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: {
// 还需要对Node和Edge去重,这里暂不考虑
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>
);
};
完整代码如下:
03. 总结与引导
以上就是 Graphin 的快速入门指南,相信大家已经看到了 Graphin 的简单易用之处。其实关于 Graphin 的使用,还有可以有很多开脑洞的想法。比如布局和数据一起改变会发生什么?大家不妨自己试试。想要深入地了解 Graphin,可以继续阅读 核心概念 和 进阶指导 两部分的内容