topology-graph-vue

🕸️ TopologyGraph Vue

🚀 基于 PixiJS v8 的高性能 Vue 3 拓扑图组件库，支持 50,000+ 节点 60 FPS 流畅渲染。

TopologyGraph Vue 面向关系图谱、组织架构、风控网络、资产关联等拓扑可视化场景，提供高性能渲染、布局算法、交互控制和 Vue 组件化集成能力。

✨ 核心特性

• ⚡ 高性能渲染：LOD 多级降级渲染、空间索引裁剪、对象池复用、GPU 预览模式与 Worker 力导向布局，支持 5 万以上节点流畅展示。
• 🎨 丰富图形能力：支持圆形、矩形、菱形、六边形、星形节点；实线、虚线、点线；直线、贝塞尔、弧线和阶梯连线，可自动翻转曲线方向并控制曲率。
• 🧭 灵活布局：内置 Barnes-Hut 力导向、四方向树形、径向与环形布局；大规模力导向计算在 Worker 中执行，可保持页面交互响应。
• 🖱️ 完整交互：支持拖拽、缩放、框选、多选、搜索定位、聚焦高亮、节点间连线绘制、撤销重做、右键菜单与图片导出。
• 🔄 增量更新：支持节点、连线的局部更新，并在更新端点时维护渲染索引与数据完整性。
• 🧩 组件化集成：提供主画布、小地图、选区操作框与浮动工具栏，支持 Vue 插件注册和按需引入。
• 🌗 主题与定制：内置亮色、暗色主题，支持运行时更新样式、性能参数、LOD 阶梯和自定义绘制回调。

🎯 适用场景

• 👥 人物、企业、股权、社交等关系图谱
• 🛡️ 资金交易、风险传播、资产关联网络
• 🏗️ 组织架构、知识图谱、服务依赖拓扑
• 🗺️ 需要高性能缩放、平移和交互的复杂可视化画布

🧭 快速导航

📦 安装 · 🚀 快速开始 · 🗂️ 数据格式 · 📚 完整参考 · 📡 事件 · ⚡ 性能建议 · 📝 更新日志

📦 安装

npm install topology-graph-vue

依赖要求：

• Node.js >= 18.0.0
• Vue ^3.3.0 || ^3.4.0 || ^3.5.0
• PixiJS ^8.17.1（自动安装）

🚀 快速开始

🌐 全局注册

import { createApp } from 'vue'
import TopologyGraph from 'topology-graph-vue'
import 'topology-graph-vue/style.css'

const app = createApp(App)
app.use(TopologyGraph)
app.mount('#app')

全局注册后可直接使用以下组件：

<template>
  <TopologyGraph @ready="onReady" @canvas-contextmenu="onContextMenu">
    <TopologyGraphMinimap position="right-bottom" />
    <TopologyGraphSelectionBox />
  </TopologyGraph>
</template>

<script setup lang="ts">
function onReady(api) {
  api.setJsonData({
    nodes: [
      { id: '1', text: '节点 1' },
      { id: '2', text: '节点 2' },
    ],
    lines: [{ from: '1', to: '2' }],
  })
  api.applyLayout({ type: 'force' })
}

function onContextMenu(event, targetType, target) {
  console.log('右键点击：', { targetType, target })
}
</script>

🧩 按需引入

<script setup lang="ts">
import { Minimap, SelectionBox, TopologyGraph } from 'topology-graph-vue'
import 'topology-graph-vue/style.css'
</script>

<template>
  <TopologyGraph @ready="onReady">
    <Minimap position="right-bottom" />
    <SelectionBox />
  </TopologyGraph>
</template>

🗂️ 数据格式

通过 setJsonData 设置图数据，兼容 relation-graph 的字段名：

api.setJsonData({
  nodes: [
    { id: '1', text: '节点 A', color: '#1890ff' },
    { id: '2', text: '节点 B', color: '#52c41a' },
  ],
  lines: [
    { from: '1', to: '2', showEndArrow: true },
  ],
})

• 节点至少需提供唯一的 id。
• 连线支持 from / to 或 source / target 两套字段。
• 节点可配置 shape、radius、color、icon、fixed 等属性。
• 连线可配置 style、curve、animation、showEndArrow 等属性。

🧰 常用 API

@ready 回调会返回图实例 API：

🔄 局部更新与连线绘制

使用局部更新 API 可避免重新设置整张图的数据：

api.updateNode('node-a', {
  text: '已更新的节点',
  color: '#f5222d',
  radius: 32,
})

api.updateLine('line-a', {
  to: 'node-c',
  text: '新的依赖关系',
  color: '#1890ff',
  curve: 'bezier',
})

updateNode() 只接受节点的持久化字段，不能修改 id、selected、hovered 或 highlighted 等交互状态。updateLine() 不能修改连线 ID；更新 from 或 to 时，两个端点必须引用已存在的节点。节点或连线不存在、端点无效时均返回 undefined，且不会修改现有数据。

可通过 API 或组件事件控制连线绘制：

api.setLineDrawingMode(true)

// 也可由业务逻辑显式指定起点和终点
api.startLineDrawing('node-a')
const line = api.finishLineDrawing('node-b')
api.cancelLineDrawing()

连续绘制模式下，依次点击两个节点即可创建连线。组件会发出 line-draw-start、line-created 和 line-draw-cancel 事件；line-created 会携带新连线、起点节点和终点节点。

🎯 视图定位

fitView() 默认适应全部可见节点。传入 nodes 或 lines 后，会将指定目标完整置于画布中心；连线的两端节点会自动纳入可见范围。

nodes 和 lines 均支持传入元素对象或 ID，且可同时使用。重复目标会自动去重。未传目标或两个数组均为空时，适应全部可见节点。

// 同时适应多个节点和连线，并聚焦全部有效目标
api.fitView({
  nodes: ['node-1', api.getNodeById('node-2')!],
  lines: ['line-1', api.getLineById('line-2')!],
  padding: 80,
  animate: true,
  duration: 400,
  focus: true,
})

// 只适应所有可见节点（不使用动画）
api.fitView()

动画期间使用 GPU 视图变换，避免逐帧完整重绘；动画结束后才进行一次完整渲染。fitView 的目标缩放范围固定为 1% 到 100%，不影响滚轮、zoomTo() 或 setViewport() 的全局缩放范围。也可继续传入数字作为边距，例如 api.fitView(80)。

🧭 布局

// 力导向布局
api.applyLayout({
  type: 'force',
  iterations: 300,
  repulsion: 2000,
  springLength: 60,
})

// 树形布局
api.applyLayout({
  type: 'tree',
  direction: 'bottom',
  levelDistance: 120,
})

// 径向或环形布局
api.applyLayout({ type: 'center' })
api.applyLayout({ type: 'circle' })

力导向布局在大数据量下会在 Worker 中异步计算，调用后可继续响应缩放、平移和取消操作。可监听布局生命周期事件处理加载状态：

<TopologyGraph
  @layout-start="layouting = true"
  @layout-end="layouting = false"
/>

🎨 运行时配置

api.setOptions({
  theme: 'dark',
  nodeAboveLines: true,
  lineDrawing: {
    preview: { style: 'dashed', color: '#faad14', width: 2 },
    line: { style: 'solid', color: '#1890ff', width: 2 },
    allowDuplicateLines: true,
  },
  lodTiers: [
    { minScale: 1, nodeMode: 'detail', lineMode: 'detail' },
    { minScale: 0.2, nodeMode: 'simple', lineMode: 'simple' },
    { minScale: 0.008, nodeMode: 'dot', lineMode: 'hide' },
  ],
})

lineDrawing.preview 只影响鼠标拖动时的临时预览线，lineDrawing.line 只影响绘制成功后自动添加的正式连线。两部分都支持 style（solid / dashed / dotted）、color 和 width，也可以在初始化配置中传入同样的结构。allowDuplicateLines 控制是否允许同一方向的重复连线，默认值为 true。

📚 完整参考

根 README 是 npm 用户文档入口。以下接口均从包中导出的 TypeScript 类型整理而来，示例中的 GraphNode、GraphLine 等类型可以直接从 topology-graph-vue 导入。

🧩 <TopologyGraph> 属性与插槽

主组件暴露 getInstance(): GraphApi，并提供两个插槽：默认插槽用于放置 Minimap、SelectionBox、GraphToolbar 等子组件，overlay 插槽用于自定义画布叠加层。上述子组件必须写在 <TopologyGraph> 的默认插槽内，不能独立挂载；业务侧应通过 @ready 保存 GraphApi，不要重新创建核心实例。

初始化优先级为：显式组件属性 width / height / theme > options 对应字段 > 默认值。未传 theme 属性时，options.theme 会生效。options 的后续响应式更新会调用 setOptions()；其中 lineDrawing、textConfig、perfConfig 和 themes 按字段合并，其余对象或数组字段整体替换。

🗺️ 子组件属性

<Minimap>

未传入 backgroundColor 时，小地图会订阅主图的主题状态：切换 light / dark 后，容器、Canvas 背景和缩放标签会同步更新。传入自定义背景色后，主题切换不会覆盖该颜色。

<SelectionBox>

无需必填属性。组件通过注入的 GraphApi 显示当前选区，支持默认删除按钮和两个插槽：默认插槽、toolbar 插槽（插槽参数包含 selectedCount、isDragging、onDelete）。选区为空时不会渲染；右键会穿透到画布，因此画布右键菜单仍可使用。

<GraphToolbar>

ButtonId 可用值：zoomIn、scale、zoomOut、fitView、resetView、fullscreen、force、tree:top、tree:bottom、tree:left、tree:right、radial、circle、download、import。

工具栏直接使用 GraphApi.isDarkTheme 响应主题变化，因此无论主题由 toggleTheme() 还是 setOptions({ theme }) 切换，工具栏的背景、边框、按钮和图标都会同步更新。

⚙️ TopologyOptions 配置

高亮开关只控制对应交互是否写入状态；通过数据或其他 API 设置的 selected / highlighted 状态仍会照常渲染。

曲线方向与偏移

lineCurveAutoReverse 仅影响未显式设置曲率的贝塞尔线和弧线：当连线端点顺序反向时，曲线会自动翻转到对应一侧，避免同一关系的反向连线重叠。需要固定弯曲侧或弯曲程度时，使用 lineCurveOffset；单条 GraphLine.curveOffset 优先于全局值。未设置偏移的平行曲线会继续自动分配不同曲率。

api.setOptions({
  lineCurve: 'bezier',
  lineCurveAutoReverse: true,
})

api.updateLine('line-a', { curve: 'arc', curveOffset: -0.18 })

// 需要全部曲线固定在同一侧时，改用全局偏移（此时自动方向不参与计算）
api.setOptions({ lineCurveOffset: 0.24 })

正负值分别控制曲线位于连线的两侧；数值越大，弯曲越明显。若需要让自动方向生效，请不要同时设置全局或单条连线的 curveOffset。

LineDrawingOptions

LineDrawingStyleOptions 的 style 为 solid / dashed / dotted，color 为 CSS 颜色（预览线传 null 恢复主题色），width 为逻辑像素宽度。

LODTier、TextConfig、ThemeConfig 与性能参数

RendererInitOptions

低配降级模式下组件会自动收紧 LOD 阈值与文字预算。存在独立背景画布时，拖拽和缩放只移动主画布的 CSS 合成层，背景网格保持不动，交互过程不重画整帧；松手或滚轮停稳后再按最终视口重绘一帧。没有独立背景画布时，交互预览仍限制在约 30fps。缩放过程中画面可能短暂发虚，停稳后恢复清晰。详情见 docs/PERFORMANCE-VS-G6.md（Git 仓库内）。正常 GPU 环境仍走原 WebGL 路径，渲染行为与旧版本完全一致。

rendererInit 必须作为组件 options 或 TopologyGraphCore.create() 的初始参数传入；实例创建后调用 setOptions({ rendererInit: ... }) 会被忽略。perfConfig.msaaLevel 为历史兼容字段，不会映射到 Pixi 初始化参数。

每个图实例分别保存主题、文字和性能配置；对一个实例调用 setOptions() 不会改动其他实例。网格颜色会写入当前实例主题，gridColor / gridSubColor 可与 theme 同时使用。DEFAULT_PERF_CONFIG 和 THEMES 仅作为新实例的默认值，不应在运行时直接修改。

连线文字未超过 maxLineTextCount 时全部绘制。超出预算时，先按 forceDetail、交互高亮和视口中心距离选择，再按相同优先级进行屏幕网格避让；候选会通过固定容量选择保留 Top K，避免大图每帧全量排序。

🎛️ GraphApi 完整方法

@ready 的参数、TopologyGraph 的 getInstance() 以及插槽子组件注入的都是 GraphApi。返回 Ref 的属性在脚本中使用 .value；Vue 模板会自动解包。

🧪 useTopologyGraph() 扩展 API

组合式函数返回 UseTopologyGraphReturn。上表中的公共方法同样可用，以下是仅组合式函数额外提供的状态或方法：performanceMode、panBy(dx, dy)、startLayout()、refresh()、getSelBoxState()；另外 doExport()、importData()、selectAll()、removeNodesByIds() 和 removeLinesByIds() 可直接使用。组合式函数还提供 minimapNodes、handleViewportChange 之外的全部选区响应式状态，适合自定义 Vue 容器或不使用主组件的场景。

FocusOptions：animate（默认 true）、duration（默认 400ms）、zoom（undefined/true 使用 focusZoom，false 保持当前比例，数字表示指定比例）。

🧱 TopologyGraphCore 与事件发射器

非 Vue 场景可通过 TopologyGraphCore.create(canvas, options) 创建核心实例。GraphApi 已覆盖常用图操作；核心实例还提供以下底层方法：

核心实例继承 EventEmitter，可调用 on(event, handler)、off(event, handler)、once(event, handler)、removeAllListeners(event?) 和 listenerCount(event)。事件名及参数参见上面的 TopologyEvents 说明。

📦 数据模型

GraphNode

GraphLine

NewNodeData 为 GraphNode 的新增输入（id、text 必填）；NewLineData 的 from、to 必填，id 可选。UpdateNodeData 是节点持久化字段的 Partial 类型，不能更新 id、selected、hovered、highlighted；UpdateLineData 不能更新 id，更新端点时必须引用已存在节点。

GraphJsonData 兼容字段

JSON 导入允许使用自身字段，也兼容 relation-graph 字段名。根对象可选 rootId；nodes 与 lines 数组中的字段如下：

节点文本优先读取 text，未提供时回退到 name；连线端点支持 from/to 或 source/target。

LayoutOptions

FitViewOptions 与图片导出

FitViewOptions 字段为 nodes、lines（元素对象或 ID 数组）、padding（默认 50）、animate（默认 false）、duration（默认 300ms）和 focus（默认 false）。fitView(80) 是只传边距的简写。

ImageExportOptions 字段为 format（image/png、image/jpeg、image/webp，默认 WebP）、quality（0~1，默认 0.85）、scale（清晰度倍率，默认 2，最高 4）和 viewportSizeMultiplier（当前视口逻辑范围倍率，默认 1）。scale 影响物理像素清晰度，viewportSizeMultiplier 只影响导出范围。

🎨 自定义绘制回调

通过 setCustomDrawCallbacks({ drawNode, drawLine }) 注册回调。回调上下文包含 node/line、屏幕坐标、当前视口缩放、Pixi graphics 对象、drawDefault() 默认绘制方法，以及 draw 工具集。工具集提供 loadImage(url)、drawImage()、drawCircle()、drawRect() 和 drawText()；自定义图形创建后需要自行添加到对应容器。

每次调用都会同时替换节点和连线回调：未传入的一侧会被清空，不会沿用上一次的函数。需要保留默认图形时先调用 ctx.drawDefault()；两侧都传 undefined 可恢复默认绘制。自定义 drawNode / drawLine 允许依赖外部状态，因此每次渲染都会执行；大图场景应避免在回调中进行昂贵计算。

📊 性能统计与基础类型

PerfStats 包含 fps、frameTime、renderTime、idle、nodeCount、lineCount、renderedNodeCount、renderedLineCount、renderedTextCount 和字符串形式的 scale。Viewport 为 { x, y, width, height, scale }；SelectionBounds 为 { minX, minY, maxX, maxY }；CanvasTargetType 为 'node' | 'line' | 'canvas'。

📡 组件事件签名

<TopologyGraph> 当前直接 emits 以下事件：

targetType 为 'node'、'line' 或 'canvas'。TopologyEvents 还导出了核心事件总线的类型映射，包含 data-change、perf-stats、history-change、selectionbox-show、selectionbox-close、layout-start、layout-end 和 options-change 等内部生命周期事件；使用 useTopologyGraph() 或 TopologyGraphCore 时可按该类型订阅。

📡 事件示例

组件支持节点、连线、画布、选择、视口和数据等事件：

<TopologyGraph
  @node-click="handleNodeClick"
  @line-click="handleLineClick"
  @line-created="handleLineCreated"
  @selection-change="handleSelectionChange"
  @canvas-contextmenu="handleContextMenu"
  @viewport-change="handleViewportChange"
/>

其中 canvas-contextmenu 的 targetType 为 node、line 或 canvas，可用于区分右键目标。连线绘制相关事件包括：line-draw-start(source)、line-created(line, source, target) 和 line-draw-cancel(source)。

⚡ 性能建议

• 节点数量超过 500 时，优先使用力导向布局并合理调大斥力与节点间距。
• 大数据量场景通过 lodTiers 开启分级渲染，缩放较小时使用 simple 或 dot 模式。
• 超过 10,000 个节点时，撤销/重做会自动禁用以控制内存占用。
• 使用 forceDetail 仅固定关键节点或关键连线，避免大量元素始终以详情模式渲染。
• 默认详细节点会自动复用未变化的形状、图标和文字；使用自定义绘制回调时该缓存不会跳过回调，应把高频计算移出回调或使用 simple / dot LOD。

🧱 非 Vue 场景

import { TopologyGraphCore } from 'topology-graph-vue'

const canvas = document.getElementById('canvas') as HTMLCanvasElement
const graph = await TopologyGraphCore.create(canvas, {
  width: 800,
  height: 600,
  theme: 'light',
})

graph.setJsonData({ nodes: [], lines: [] })
graph.applyLayout({ type: 'force' })
graph.fitView()

📄 License

MIT