vue-honeycomb

交互式蜂巢图（Honeycomb Graph）Vue 3 组件，基于 CSS clip-path 实现六边形节点，无需 canvas。配套可平移缩放画布，可用于知识图谱、技能树、地图缩略图等场景。

在线演示

GitHub Pages Demo

特性

• 节点内放任意 Vue 内容：六边形只是 CSS 切的外形，内部还是普通 div，可以放任何组件、图标、绑定、动画
• 位置全靠 CSS 变量：JS 不参与布局计算，性能稳定
• 同奇偶坐标系：[x, y] 必须同奇偶，比 offset / axial 坐标更直观，邻居计算简单
• 可平移缩放画布：原生支持鼠标拖拽 + 滚轮缩放 + 双指 pinch + 双击重置

安装

bun add vue-honeycomb

使用

<template>
  <HoneycombGraph :load-data="loadData" />
</template>

<script setup lang="ts">
import { HoneycombGraph, type HoneycombGraphRootNode } from 'vue-honeycomb'

async function loadData(id?: string): Promise<HoneycombGraphRootNode> {
  // 返回当前节点及其子节点
  return {
    id: id ?? 'root',
    label: '根节点',
    children: [
      { id: '1', label: '子节点 1' },
      { id: '2', label: '子节点 2' },
    ],
  }
}
</script>

<style>
@import 'vue-honeycomb/style.css';
</style>

坐标系

       (−1, 1)   (1, 1)
            \   /
             \ /
   (−2, 0)──(0, 0)──(2, 0)
             / \
            /   \
       (−1,−1)  (1,−1)

规则：坐标 [x, y] 要求 x、y 同奇偶。

• 合法：[0,0]、[2,0]、[-2,0]、[1,1]、[-1,-1]、[3,1] ...
• 非法：[1,0]、[0,1]、[2,1] ...

这套坐标系的好处：邻居规则简单且对称（一级邻居就是 [±1,±1] 和 [±2,0]），不像 offset 坐标要分奇偶行不同处理。

工具函数

import {
  isSamePoint,              // 判断两点是否相同
  inPoints,                 // 判断点是否在数组中
  calcRelativePosition,     // a 是 b 的第几个邻居（0..5，-1 表示不相邻）
  buildGroundPointsLevel1,  // 一级邻居（6 个）
  buildGroundPointsLevel2,  // 二级邻居（12 个）
} from 'vue-honeycomb'

buildGroundPointsLevel1([0, 0])
// → [[-1,1], [1,1], [2,0], [1,-1], [-1,-1], [-2,0]]

calcRelativePosition([2, 0], [0, 0])
// → 2  （右邻居方向）

样式定制

通过 CSS 变量覆盖（在 .hexagonal-layout 或全局）：

.hexagonal-layout {
  --hexagonal-layout-item-size: 80px;    /* 单元宽度 */
  --hexagonal-layout-item-offset: 4px;   /* 相邻单元的额外间距 */
}

.honeycomb-graph-item {
  background: linear-gradient(135deg, #1770e5, #4f46e5);
}

Props

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | loadData | (id?: string) => Promise<HoneycombGraphRootNode> | 必填 | 加载节点数据的函数 | | colorGroup | BackgroundColor[] | 内置配色 | 自定义节点配色组，每组为 [normal, hover, primary] | | itemSize | number | 60 | 六边形节点大小（px） |

事件

• root-change(root): 当前根节点变化时触发
• node-select(node, root?): 选中节点时触发
• cancel-select: 取消选中时触发

开发

# 安装依赖
bun install

# 启动演示
bun run dev

# 构建库（纯 Bun，输出 JS/CSS）
bun run build:lib

# 生成 TypeScript 类型声明（需 Node.js 兼容环境）
bun run build:types

# 构建演示
bun run build:demo

# 类型检查
bun run typecheck

发布

发布到 npm 前，请执行 prepublishOnly 脚本，确保同时构建库产物和类型声明：

bun run prepublishOnly
npm publish --registry https://registry.npmjs.org/

配套

与 vue-board-graph 共享同款交互模式，可以混合使用：蜂窝图做"概念近邻"视图，棋盘图做"实体关系"视图。

License

MIT © 2026 Liu Xiaosong