快速上手

安装

  1. $ npm install @antv/graphin --save

第一个例子

这是一个最简单的 Graphin 组件的在线演示。访问 https://codesandbox.io/s/data-driven-fkue0 创建一个 CodeSandbox 的在线示例,别忘了保存以创建一个新的实例。通过 CodeSandbox,我们可以不用去配那些琐碎的 React 脚手架,快速尝鲜。

01. 渲染数据

Graphin 使用起来就像普通的组件一样,它只有一个必选属性 data,内部会对其进行数据校验,data 的数据结构有一定的要求,详情参考:核心概念/Data 数据驱动

Graphin 提供一个 Mock 函数,帮助我们快速生成一些图数据,让我们试试看吧:

  1. import React from 'react';
  2. import ReactDOM from 'react-dom';
  3. import Graphin, { Utils } from '@antv/graphin';
  4. import "@antv/graphin/dist/index.css"; // 引入Graphin CSS
  5. import './styles.css';
  6. const App = () => {
  7. const data = Utils.mock(10).graphin();
  8. return (
  9. <div className="App">
  10. <Graphin data={data} />
  11. </div>
  12. );
  13. };
  14. const rootElement = document.getElementById('root');
  15. ReactDOM.render(<App />, rootElement);

这个例子的效果可以看上一节中的 Sandbox 例子。

02. 使用布局

Graphin 组件内置了 6 种布局,默认提供布局为 concentric(同心圆布局)。我们可以根据自己业务的不同来调整布局。比如,我们希望节点按照里力导(force)排列。让我们来调整上述的代码:

  1. - <Graphin data={data} />
  2. + <Graphin data={data} layout={{name:"force"}}/>

效果如下:

03. 配置 Node 和 Edge 样式

想要修改 Graphin 的节点和边的样式,我们可以直接修改 data 上的数据:

data.nodedata.edge 上的各个属性,比如 shapestyle 等等和 G6 节点和边数据上的是一样的。这里会透传给 G6。这里的配置可以参考 G6 的文档:内置节点内置边。 需要注意的是,如果传入的数据没有 shape,Graphin 给节点的默认 shape 是内置的自定义的 CircleShape。默认的边是内置的自定义 LineEdge。 ### 04. 使用组件 Graphin 目前仅提供两个官方组件,Toolbar 和 ContextMenu。关于它们,你们可以在核心概念/Components 分析组件中得到更详细的介绍,我们以添加组件 Toolbar 为例: - 安装组件,graphin 分析组件发布在单独的 NPM 包 graphin-components 中:
  1. $ npm install @antv/graphin-components save

Graphin-components 基于 antd 组件,因此如果是非 antd 项目,需要手动引入 antd 的 css

- 将组件放在 Graphin 组件内部,这样 Graphin 组件可以将 graphapis 等属性传递给分析组件:
  1. import React from 'react';
  2. import ReactDOM from 'react-dom';
  3. import Graphin, { Utils } from '@antv/graphin';
  4. import { Toolbar } from '@antv/graphin-components';
  5. import "@antv/graphin/dist/index.css"; // Graphin CSS
  6. import "@antv/graphin-components/dist/index.css"; // Graphin 组件 CSS
  7. import './styles.css';
  8. const App = () => {
  9. const data = Utils.mock(10).circle().graphin();
  10. return (
  11. <div className="App">
  12. <Graphin data={data} layout={{ name: 'concentric' }}>
  13. <Toolbar />
  14. </Graphin>
  15. </div>
  16. );
  17. };
  18. const rootElement = document.getElementById('root');
  19. ReactDOM.render(<App />, rootElement);
效果如下: 关于 Graphin 组件,我们可以到 Grapin Studio 中去体验一下功能: - todo/redo 撤销重做功能 - zoomIn/out 缩小放大功能 - fullscreen 全屏功能 - contextmenu 右键菜单 ### 04. 事件监听 图分析有着非常丰富的事件,如果我们想监听事件,该如何做呢? - - 得到 Graphin 的 Ref 实例 - - 使用 G6 的 graph 进行事件监听 代码如下:
  1. const App = () => {
  2. const data = Utils.mock(10).graphin();
  3. const graphRef = React.createRef(null);
  4. React.useEffect(() => {
  5. const { graph } = graphRef.current;
  6. graph.on('node:click', e => {
  7. console.log('node:click', e);
  8. });
  9. }, []);
  10. return (
  11. <div className="App">
  12. <Graphin data={data} layout={{ name: 'concentric' }} ref={graphRef}>
  13. <Toolbar />
  14. </Graphin>
  15. </div>
  16. );
  17. };
### 05. 总结与引导 通过上面的 4 步,我们基本了解了 Graphin 的全部 4 个核心概念 data(数据)、layout(布局)、components(分析组件),events(数据)。 ## 开发点有趣的功能 通过上文,聪明的小伙伴已经发现了,Graphin 的设计完全遵照了 React 的编程模型,声明式的完成了从数据到视图的映射。现在让我们一起来开发两个有趣的功能,布局切换节点扩散。 ### 01. 布局切换

同一组数据,改变布局算法会产生不一样的布局效果,从而满足人们的分析需求。

因为 Graphin 是 React 组件,改变 props.layout 就能改变视图的布局效果,因此我们只要把多种布局 layouts 组合起来,每次切换改变 props.layout 即可。 - - 设计布局切换 LayoutSelector组件的接口。
  1. interface Layout {
  2. name: string;
  3. options: {
  4. [key: string]: any;
  5. };
  6. }
  7. interface LayoutSelectorProps {
  8. / 所有的内置布局/
  9. layouts: Layout[];
  10. / 当前的布局 /
  11. value: Layout;
  12. / 切换布局的事件 /
  13. onChange: (vale: Layout) => void;
  14. }
  15. <LayoutSelector layouts={layouts} value={currentLayout} onChange={handleChange} />;
- - 获取 Graphin 支持的内置布局列表 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 即可。
  1. import React from 'react';
  2. import ReactDOM from 'react-dom';
  3. import Graphin, { Utils } from '@antv/graphin';
  4. import { Toolbar } from '@antv/graphin-components';
  5. const App = () => {
  6. const [state, setState] = React.useState({
  7. selected: [],
  8. data: Utils.mock(10).graphin(),
  9. });
  10. const { data, selected } = state;
  11. const graphRef = React.createRef(null);
  12. React.useEffect(() => {
  13. const { graph } = graphRef.current;
  14. const onNodeClick = e => {
  15. console.log('node:click', e);
  16. setState({
  17. ...state,
  18. selected: [e.item.get('model')],
  19. });
  20. };
  21. graph.on('node:click', onNodeClick);
  22. return () => {
  23. graph.off('node:click', onNodeClick);
  24. };
  25. }, [state]);
  26. const onExpand = () => {
  27. const count = Math.round(Math.random() * 40);
  28. const expandData = Utils.mock(count)
  29. .expand(startNodes)
  30. .graphin();
  31. setState({
  32. ...state,
  33. data: {
  34. // 还需要对Node和Edge去重,这里暂不考虑
  35. nodes: [...state.nodes, ...expandData.nodes],
  36. edges: [...state.edges, ...expandData.edges],
  37. },
  38. });
  39. };
  40. return (
  41. <div className="App">
  42. <button onClick={onExpand}>Node Expand</button>
  43. <Graphin data={data} layout={{ name: 'concentric' }} ref={graphRef}>
  44. <Toolbar />
  45. </Graphin>
  46. </div>
  47. );
  48. };

完整代码如下:

03. 总结与引导

以上就是 Graphin 的快速入门指南,相信大家已经看到了 Graphin 的简单易用之处。其实关于 Graphin 的使用,还有可以有很多开脑洞的想法。比如布局和数据一起改变会发生什么?大家不妨自己试试。想要深入地了解 Graphin,可以继续阅读 核心概念进阶指导 两部分的内容