Skip to content

Latest commit

 

History

History
263 lines (191 loc) · 9.71 KB

README.zh-CN.md

File metadata and controls

263 lines (191 loc) · 9.71 KB
Raw

XFlow: 专业的图编辑应用级解决方案

npm package npm downloads Percentage of issues still open

什么是 XFlow？

XFlow 是 AntV 旗下, 基于 X6 图编辑引擎、面向 React 技术栈用户的图编辑应用级解决方案, 旨在让复杂的图编辑应用开发变得简单高效。XFlow 源自蚂蚁体验技术部数据智能团队, 已经在蚂蚁大数据部、人工智能中台业务场景深度打磨验证, 值得信赖！

✨ 特性

  • 🌱 　极易定制：支持使用 React 组件 开发节点/连线样式。
  • 🚀 　开箱即用：内置 1 个快速上手 + 3 个解决方案, 内置若干 React 交互组件, 如小地图、对齐线、右键菜单等。
  • 💯 　生产可用：源自蚂蚁体验技术部数据智能团队, 在蚂蚁大数据部、人工智能中台业务场景深度打磨验证。
  • 🧲 　 一切皆可扩展：内置统一的扩展模式, 可按照自己的业务需求扩展图交互, 所有组件皆可扩展。

🔨 应用案例

简单示例

流程图解决方案

DAG 解决方案

ER 图解决方案

⌨️ 安装

使用 npm 或 yarn:

#npm
$ npm install @antv/xflow --save

#yarn
$ yarn add @antv/xflow

使用 cdn:

通过 script 标签引入, 可以使用下面两个 CDN 中的任何一个, 默认返回 XFlow 的最新版:

<script src="https://unpkg.com/@antv/xflow/dist/index.umd.js"></script>

对于生产环境, 我们推荐使用一个明确的版本号, 以避免新版本升级造成不可预期的破坏:

开始使用

Step1 创建工作空间

首先, 我们需要构建一个 XFlow 工作空间，其中 XFlowCanvas 画布组件，CanvasScaleToolbar 工具栏、CanvasMiniMap 小地图、CanvasSnapline 对齐线等交互组件，都是 XFlow 工作空间中的内容。需要强调的是，在XFlow 中，一切都是React 组件。

import { XFlow, XFlowCanvas } from '@antv/xflow'
import { CanvasScaleToolbar, CanvasMiniMap, CanvasSnapline } from '@antv/xflow-extension'
import { useGraphConfig } from './config-graph'

return (
  <XFlow
    className="xflow-uer-container"
    graphData={graphData}
    graphLayout={{
      layoutType: 'dagre',
      layoutOptions: {
        type: 'dagre',
        rankdir: 'TB',
        nodesep: 60,
        ranksep: 40,
      }
    }}
    onLoad={onLoad}
    isAutoCenter={true}
  >
    <XFlowCanvas config={useGraphConfig()}>
      {/** 工具栏 */}
      <CanvasScaleToolbar />
      {/** 小地图  */}
      <CanvasMiniMap minimapOptions={{ width: 200, height: 120 }} />
      {/** 对齐线 */}
      <CanvasSnapline color="#1890ff" />
    </XFlowCanvas>
  </XFlow>
)

Step2 设置相关配置

然后, 我们需要设置画布全局配置项 graphConfig, 该配置项决定了画布上的内容如何呈现。比如画布是否需要网格、画布的缩放等级、画布是否支持滚轮缩放等, 再比如画布上需要渲染哪种类型的 React 节点/连线等。

import { createGraphConfig } from '@antv/xflow'
import Node1 from './react-node/node1'
import Edge1 from './react-edge/edge1'

export const useGraphConfig = createGraphConfig(config => {
  /** 设置画布配置项，会覆盖XFlow默认画布配置项 */
  config.setX6Config({
    grid: true,
    scaling: { min: 0.2, max: 3 },
    mousewheel: { enabled: true, zoomAtMousePosition: true },
  })

  /** 设置画布需要渲染的React节点、连线上的React内容 */
  config.setNodeRender('NODE1', props => <Node1 {...props} />)
  config.setEdgeRender('EDGE1', props => <Edge1 {...props} />)
})

Step3 画布渲染等逻辑操作

设置相关配置后, 我们就可以在 onLoad 方法里进行一些必要的业务逻辑操作，比如从服务端获取数据、执行布局算法、渲染画布内容、监听画布相关事件等。

/** XFlow初始化完成后的回调 */
const onLoad: IAppLoad = async app => {
  /** 这里我们假设数据已经从服务端取到 */
  const nodes: NsGraph.INodeConfig[] = [
    { id: 'root1', width: 150, height: 40, renderKey: 'NODE1', info: { text: 'root1' } },
    { id: 'down1', width: 150, height: 40, renderKey: 'NODE2', info: { text: 'down1' } },
    { id: 'down2', width: 150, height: 40, renderKey: 'NODE2', info: { text: 'down2' } },
    { id: 'down3', width: 150, height: 40, renderKey: 'NODE2', info: { text: 'down3' } },
  ]
  const edges: NsGraph.IEdgeConfig[] = [
    {
      id: 'root1-down1',
      source: 'root1',
      target: 'down1',
      renderKey: 'EDGE1',
      info: { line: 'root1-down1' },
    },
    {
      id: 'root1-down2',
      source: 'root1',
      target: 'down2',
      renderKey: 'EDGE2',
      info: { line: 'root1-down2' },
    },
    {
      id: 'root1-down3',
      source: 'root1',
      target: 'down3',
      label: '1:N(纯文本)',
      info: { line: 'root1-down3' },
    },
  ]
  const graphData = { nodes, edges }
  setGraphData(graphData)

  /** 监听画布事件 */
  const graph = await app.getGraphInstance()
  graph.on('node:click', ({ e, x, y, node, view }) => {
    const nodeData: NsGraph.INodeConfig = node.getData()
    message.success(`${nodeData.id}节点被点击了`)
  })
  graph.on('edge:click', ({ e, x, y, edge, view }) => {
    edge.toFront()
    const edgeData: NsGraph.IEdgeConfig = edge.getData()
    message.success(`${edgeData.id}连线被点击了`)
  })
}

到此，一个简单的图形应用已经具备雏形了。但 XFlow 的魅力远不止于此！如果您的应用还需要各种交互组件，XFlow 为您内置了若干交互组件，拿来即用，比如上面使用的 CanvasScaleToolbar工具栏，CanvasMinimap小地图，CanvasSnapline对齐线。

另外 XFlow 真正强大之处在于:

  • 画布组件与交互组件的联动机制。
  • XFlow 提供的扩展机制允许定制任意业务需要的交互组件。您可以在后面的教程中详细了解。

使用文档

XFlow 使用文档

如何交流

如果你在使用的过程中碰到问题，可以先通过 issues 看看有没有类似的 bug 或者建议。欢迎提 issues 交流，也可以使用钉钉扫描下面二维码加入XFlow 交流群。

需要注意的是，提问题时请配上 CodeSandbox 的复现代码，方便快速定位和解决问题。

X6/XFlow 图可视化交流群1

如何开发

我们使用了 pnpm 来管理项目, 目录结构如下:

├── packages
│   ├── xflow-docs            # XFlow 使用文档, 包含 1个快速开始 + 3个解决方案
│   ├── xflow                 # 所有 XFlow 相关的引用都从 xflow 库导出
│   ├── xflow-core            # XFlow 对于 X6 画布的封装 graphProvider, 提供若干内置命令Command, 提供全局ModelService等
│   ├── xflow-extension       # XFlow 内置的若干交互组件, 包括小地图、对齐线、右键菜单等
│   └── xflow-hook            # XFlow 内置的 hook 机制, 允许自定义若干默认行为
  1. 开始之前需要安装必要的全局依赖和初始化：
# 全局安装 pnpm
$ npm install pnpm -g

# 安装项目依赖和初始化构建
$ pnpm install
  1. 启动 dev server

新建 terminal 监听 xflow-core 的文件变化，等待 watch 服务启动成功后执行下个命令。

yarn run dev:core

新建 terminal 监听 xflow-extension 的文件变化，等待 watch 服务启动成功后执行下个命令。

yarn run dev:ext

新建 terminal 监听 xflow 的文件变化，等待 watch 服务启动成功后执行下个命令。

yarn run dev:main
  1. 启动文档网站, 根据示例调试代码
yarn run dev:docs

如何贡献

如果你在使用的过程中碰到问题，可以先通过 issues 看看有没有类似的 bug 或者建议。

如需提交代码，请遵从我们的贡献指南。我们会收集贡献者的 Github 头像到下面贡献者清单中。

Contributors