探秘@antv/x6 与@antv/hierarchy 的奇妙结合与使用

一、@antv/x6 与 @antv/hierarchy 简介

（一）@antv/x6 概述

AntV 旗下的 @antv/x6 是一款极易定制、开箱即用且数据驱动的图编辑引擎。它在数据可视化领域有着重要地位与作用，能够助力开发者轻松搭建诸如 DAG 图（有向无环图）、ER 图（实体关系图）、流程图等各类应用。

@antv/x6 基于 HTML5 Canvas 和 SVG 技术来实现其强大功能。一方面，它利用了 Canvas 和 SVG 的优势，对大量图形进行分层处理，哪怕是面对大规模数据和复杂交互场景，也能够实现高效且平滑的动画渲染，始终保持流畅性能。例如在绘制复杂的业务流程图，涉及众多图形元素和交互操作时，它的性能优势就得以凸显。

另一方面，它支持多种交互模式与丰富的自定义扩展。像节点拖放、连线绘制、旋转缩放等图形操作它都可以轻松实现，同时还提供了大量的预置图形和连接器样式，以满足多样化的设计需求。比如在创建网络拓扑图时，开发者可以利用这些功能便捷地描绘设备间的连接状态和通信路径。

此外，@antv/x6 具备丰富的交互 API，提供了完善的事件监听与处理机制，能够方便地绑定各种交互逻辑，像点击、拖动、双击等常见交互事件都能快速响应，便于开发者迅速实现功能丰富的图形应用。其插件化架构更是一大亮点，允许开发者轻松扩展新功能或替换已有功能，极大增强了框架整体的灵活性和可维护性，无论是在 UI 原型设计阶段快速搭建界面布局原型，还是在产品后续迭代中添加新功能，都能很好地满足需求。

（二）@antv/hierarchy 概述

@antv/hierarchy 是专为可视化层次数据设计的布局算法库。在可视化项目中，当涉及到展示具有层级关系的数据时，它就发挥出关键作用。

它拥有多种高效且美观的布局方式，例如紧凑盒式（Compact Box）、树状图等布局类型。这些不同的布局方式适用于各种各样的场景，其中在组织架构图、思维导图等方面应用尤为广泛。比如企业要展示自身的组织架构，通过 @antv/hierarchy 提供的布局算法，可以清晰、直观地呈现出各个部门、岗位之间的层级关系；又或者在制作思维导图用于梳理思路、整理知识体系时，也能借助它让内容结构一目了然。

值得一提的是，@antv/hierarchy 基于 MIT 许可协议开源，这意味着广大开发者可以自由地使用它，并且能够根据自身业务需求对其进行二次开发，将其更好地集成到不同的数据可视化项目当中，为项目的可视化展示效果添砖加瓦。

二、安装与基础配置

（一）@antv/x6 安装与引入

在使用 @antv/x6 时，首先需要进行安装与引入操作。我们可以通过常用的包管理工具 npm 或 yarn 来完成安装，具体命令如下：

• 使用 npm 安装：在命令行中输入$ npm install @antv/x6 --save，这条命令会将 @antv/x6 包下载并安装到你的项目中，同时将其依赖信息保存到项目的package.json文件里，方便后续管理和项目部署等操作。例如在一个新建的数据可视化项目中，如果你想使用 @antv/x6 来构建流程图等图形应用，执行此命令就能快速准备好相应的基础代码库。

• 使用 yarn 安装：输入$ yarn add @antv/x6命令，yarn 同样会将 @antv/x6 包添加到项目中，它有着高效的依赖处理机制，在安装过程中能够更快速地解析和下载依赖包。像在多人协作开发的大型项目里，使用 yarn 安装可以保证各个开发人员的依赖环境更加一致和稳定，便于项目整合与调试。

安装完成后，便可以根据项目需求在相应的代码文件里进行引入使用了，比如在 JavaScript 模块中通过import语句来引入相关模块，进而利用 @antv/x6 提供的丰富功能去构建各种可视化图形应用。

（二）@antv/hierarchy 安装与引入

对于 @antv/hierarchy，其安装过程同样便捷，同样支持 npm 和 yarn 两种方式：

• 使用 npm 安装：在命令行输入npm install @antv/hierarchy --save，执行该命令后，@antv/hierarchy 包就会被安装到项目目录下，并且项目的依赖配置文件也会相应更新，记录好这个包的相关信息。例如当你要开发一个展示企业组织架构的可视化项目时，这个安装步骤就是使用其布局算法的前置操作。

• 使用 yarn 安装：只需在命令行执行$ yarn add @antv/hierarchy命令即可。通过 yarn 来安装，能够利用它自身的优势，更快速准确地获取和整合依赖，确保项目中可以顺利使用 @antv/hierarchy 提供的各种布局算法，以便后续处理和展示具有层级关系的数据，像在制作思维导图应用时，就能依靠它来实现清晰美观的布局呈现。

安装完毕后，按照相应的开发规范和语法，在代码中引入该库，就可以调用其内部的布局算法等功能，助力数据可视化项目更好地展示层级数据了。

三、@antv/x6 的核心使用要点

初始化图表

初始化图表是使用@antv/x6的重要一步，以下是相关的代码示例及说明：

async initGraph() {
      // 检查是否存在当前图表实例，如果存在，则清空画布
      if (this.graph) {
        this.graph.clearCells()
      }
      
      // 将图表的数据设置为组件中的x6Data
      await this.graph.fromJSON(this.x6Data)
    }

在上述代码中，首先会判断是否已经存在图表实例，如果存在的话，就通过clearCells方法清空画布上已有的元素，为新的数据展示做准备。然后，使用fromJSON方法将组件中的x6Data数据加载到图表实例中，从而完成图表的初始化工作。这个x6Data通常是按照@antv/x6要求的格式组织好的数据，比如包含节点、边等相关信息的数据结构，如此一来，就能基于这些数据在画布上渲染出对应的图形元素，构建出想要的图表了。

四、@antv/hierarchy 的布局运用

（一）布局类型与选择

@antv/hierarchy 提供了多种实用的布局类型，以满足不同场景下可视化层次数据的需求。

常见的布局类型有紧凑盒式（Compact Box）布局，它能够将具有层级关系的数据节点紧凑地排列在一起，适用于节点数量较多且层级结构相对复杂，但又希望在有限空间内清晰展示各层级关系的情况，比如在展示大型企业复杂的组织架构图时，紧凑盒式布局可以很好地呈现出各个部门、团队以及岗位之间层层嵌套的关系，让整体结构一目了然。

还有树状图布局，这种布局方式以树状的结构来展现数据层级，根节点位于顶部或者一侧（取决于具体设置的方向参数），然后依次展开子节点，非常直观形象，常用于思维导图、文件目录结构展示等场景。例如制作一个知识梳理的思维导图，利用树状图布局可以清晰地体现出各个知识点之间的从属关系，方便理解和记忆。

在面对不同的数据结构和可视化需求时，选择合适的布局方式至关重要。如果数据的层级较深，且各层级节点数量分布较为均匀，同时希望突出整体的层级脉络，那么树状图布局会是不错的选择；而若数据节点繁多，需要在有限的可视化区域内尽可能多地展示节点以及它们之间的关联，并且对展示的紧凑性有较高要求，紧凑盒式布局则更能发挥优势。另外，还需要考虑展示的目的和受众，如果是给普通用户展示简单的分类关系，可能简洁明了的布局更容易被接受；若是面向专业人员进行详细的数据结构剖析，可能就需要根据具体业务逻辑选择更能精准呈现数据特点的布局方式了。

（二）布局参数配置

在使用 @antv/hierarchy 布局时，合理配置各项参数能够让可视化效果达到理想状态。下面为大家介绍一些常用参数的含义与作用以及如何通过代码示例来进行调整。

1. 方向（direction）参数：该参数用于指定布局的整体方向，比如常见的取值有 "LR"（从左至右）、"RL"（从右至左）、"TB"（从上至下）、"BT"（从下至上）等。以下是一个示例代码，展示如何设置紧凑盒式布局的方向为从左至右：

const { compactBox } = require('@antv/hierarchy');
const root = {
    id: 'root',
    children: [
        {
            id: 'child1',
            children: [
                { id: 'subChild1' },
                { id: 'subChild2' }
            ]
        },
        { id: 'child2' }
    ]
};
const layoutedTree = compactBox(root, {
    direction: 'LR'  // 设置方向为从左至右
});
console.log(layoutedTree);

通过这样的设置，布局后的节点会按照从左至右的顺序依次排列，方便展示横向的层级关系，适用于如时间轴相关的层级数据展示或者某些需要横向展开的组织架构等情况。

2. 节点宽度（getWidth）和高度（getHeight）参数：这两个参数用于自定义节点在可视化界面中的尺寸大小。它们通常接受一个函数作为参数，函数的参数为对应的数据节点对象，根据节点数据的不同可以返回不同的宽度和高度值。示例代码如下：

const { compactBox } = require('@antv/hierarchy');
const root = {
    id: 'root',
    children: [
        {
            id: 'child1',
            children: [
                { id: 'subChild1' },
                { id: 'subChild2' }
            ]
        },
        { id: 'child2' }
    ]
};
const layoutedTree = compactBox(root, {
    getWidth: d => 30,  // 自定义节点宽度为30
    getHeight: d => 30  // 自定义节点高度为30
});
console.log(layoutedTree);

在上述代码中，所有节点的宽度和高度都被统一设置成了 30，不过在实际应用中，可以根据节点的重要性、内容多少等因素编写更复杂的函数逻辑来动态地确定每个节点的具体尺寸，使可视化效果更加合理美观。

3. 间距相关参数（如水平间距 getHGap、垂直间距 getVGap 等） ：这些参数用于控制节点与节点之间的间隔距离，确保布局不会过于拥挤或者稀疏。比如在树状图布局中，如果想要节点之间在水平方向有更大的间隔，可以通过调整水平间距参数来实现。示例如下：

const Hierarchy = require('@antv/hierarchy');
const treeData = { /* 这里定义你的树形数据结构 */ };
const compactBoxLayout = Hierarchy.compactBox(treeData, {
    getHGap: () => 80,  // 设置水平间距为80
    getVGap: () => 5   // 设置垂直间距为5
});

通过调整这些间距参数的值，可以根据实际可视化区域的大小以及数据的特点，让整个布局看起来更加协调，方便用户清晰地分辨各个节点及其层级关系。

总之，通过灵活调整这些布局参数，可以根据具体的数据和展示需求，打造出满足个性化要求的、高质量的数据可视化布局效果，更好地呈现出层次数据所蕴含的信息。

五、@antv/x6 与 @antv/hierarchy 的结合实践

打造组织结构图

组织结构图也是常见的数据可视化展示形式，下面介绍如何结合 @antv/x6 与 @antv/hierarchy 来创建组织结构图。

1. 数据准备

对于组织结构图，首先要整理好代表组织架构层级关系的数据，通常是一个树形结构的数据，例如：

const orgData = {
    id: 'root',
    label: '公司总部',
    children: [
        {
            id: 'department1',
            label: '部门1',
            children: [
                {
                    id: 'team1',
                    label: '小组1'
                },
                {
                    id: 'team2',
                    label: '小组2'
                }
            ]
        },
        {
            id: 'department2',
            label: '部门2',
            children: [
                {
                    id: 'team3',
                    label: '小组3'
                }
            ]
        }
    ]
};

这个数据结构清晰地展示了公司从总部到各个部门，再到部门下属小组的层级关系，每个节点包含了唯一的id、显示的label以及子节点的children信息（如果有的话）。

2. 运用合适的布局

这里适合采用 @antv/hierarchy 提供的树状图布局方式来展示组织结构的层级关系，代码如下：

import Hierarchy from '@antv/hierarchy';
const layoutedOrgData = Hierarchy.compactBox(orgData, {
    direction: 'TB',  // 设置布局方向从上至下，符合常见组织结构图展示习惯
    getWidth: () => 150,  // 自定义节点宽度
    getHeight: () => 60,  // 自定义节点高度
    getHGap: () => 20 // 自定义节点间距
});

通过这样的布局设置，能够让组织结构图以树状形式，从上到下依次展示各个层级的组织单元，清晰呈现出组织的架构情况。

3. 添加节点与关联关系

使用 @antv/x6 来创建组织结构图中的各个节点，并根据数据中的关联关系添加边来连接相应的节点，示例代码如下：

import { Graph } from '@antv/x6';
const graph = new Graph({
    container: document.getElementById('org-chart-container'),
    width: 800,
    height: 600,
    background: {
        color: '#F2F7FA'
    }
});
const model = { nodes: [], edges: [] }
function traverse(data) {
    if (data) {
        model.nodes?.push({
            id: data.id,
            shape: 'rect',
            label: data.label,
            x: 0,
            y: 0
        });
        if (data.children && data.children.length > 0) {
            data.children.forEach(child => {
                traverse(child);
                model.edges?.push({
                    source: data.id,
                    target: child.id
                });
            });
        }
    }
}
traverse(layoutedOrgData);
graph.fromJSON(model)

在上述代码中，通过递归的方式遍历组织结构数据，创建x6需要的数据让x6进行构建，最终构建出完整的组织结构图。

通过这样的结合使用，可以充分发挥 @antv/x6 在图形绘制与交互方面以及 @antv/hierarchy 在布局层级数据上的优势，打造出清晰、美观且交互友好的组织结构图，方便展示和查看组织内部的架构关系等信息。

@antv/x6 文档地址

@antv/hierarchy git地址