vue3-network-graph

vue3-network-graph 使用说明

基于 Vue 3 + SVG 的轻量级网络拓扑图组件，无第三方图表库依赖。支持节点拖拽、画布无限平移、滚轮缩放、连线流向动画、三种连线模式、同节点对多连线防重叠、连线文字沿线直立等能力。

目录

• 名称
• 描述
• 使用方法
• 使用例子
• 全局配置属性说明
• 节点属性说明
• 连线属性说明
• 调用方法
• 事件说明
• 交互操作

名称

vue3-network-graph - Vue3 网络拓扑图组件

描述

一个纯 SVG 实现的轻量级网络拓扑图组件，提供以下核心能力：

核心功能

• 多种连线模式：直线（straight）/ 折线（polyline）/ 曲线（curve）
• 智能多线处理：同一对节点的多条连线自动防重叠，任何模式下都保持平行
• 连线文字直立：fromText / centerText / toText 沿路径切向旋转，超过±90° 自动翻转保持可读
• 丰富的节点类型：8 种图标节点 + 文本节点 + 纯边框节点
• 2D/3D 视图：支持 2D 平面和 2.5D 卡片风格
• 流向动画：虚线流光 + 粒子效果，可单独控制每条连线的动画开关

交互能力

• 节点操作：拖拽移动、拖拽调整尺寸、多选整体拖动
• 画布操作：无限平移（空白左键/中键）、滚轮缩放（0.2x–5x）
• 选择模式：单击选中、Ctrl+ 点击多选、Ctrl+ 左键框选
• 连线创建：从节点手柄拖拽到目标节点自动连线
• 图层管理：Z 轴排序、右键菜单、快捷键操作（需启用 enableZOrder）

性能优化

• 自动降级：装饰动效根据规模自动关闭（连线>200 关流光、>500 关发光、节点>300 关呼吸）
• 大图性能：千级节点可流畅平移/拖拽，密集图形下节点优先响应点击

使用方法

1. 安装

npm install vue3-network-graph
# 或：pnpm add vue3-network-graph | yarn add vue3-network-graph

2. 引入组件

// main.js
import { createApp } from "vue";
import { Topology } from "vue3-network-graph";
import "vue3-network-graph/style.css";

const app = createApp(App);
app.component("Topology", Topology);
app.mount("#app");

或局部引入：

<script setup>
import { Topology } from "vue3-network-graph";
import "vue3-network-graph/style.css";
</script>

3. 基本使用

<template>
  <Topology
    ref="topoRef"
    :editable="true"
    v-model:nodes="myNodes"
    v-model:edges="myEdges"
    :config="config"
    @node-click="handleNodeClick"
    @selection-change="handleSelectionChange"
  />
</template>

<script setup>
import { ref } from "vue";
import { Topology } from "vue3-network-graph";

const myNodes = ref([
  { id: "node1", label: "节点 1", type: "core", state: "normal", x: 0, y: 0 },
  {
    id: "node2",
    label: "节点 2",
    type: "server",
    state: "normal",
    x: 200,
    y: 100,
  },
]);

const myEdges = ref([
  { id: "edge1", from: "node1", to: "node2", centerText: "连接" },
]);

const config = ref({
  showGrid: true,
  nodeDraggable: true,
  nodeResizable: true,
});
</script>

使用例子

完整示例

<template>
  <div class="topology-container">
    <Topology
      ref="topoRef"
      :editable="true"
      v-model:nodes="nodes"
      v-model:edges="edges"
      v-model:line-mode="lineMode"
      v-model:view-mode="viewMode"
      :groups="groups"
      :config="config"
      @node-click="onNodeClick"
      @edge-select="onEdgeSelect"
      @selection-change="onSelectionChange"
      @data-change="onDataChange"
      @edge-create="onEdgeCreate"
    >
      <!-- 自定义节点图标插槽 -->
      <template #node-icon="{ node, color, viewMode }">
        <circle r="16" :fill="color" opacity="0.9" />
      </template>
    </Topology>
  </div>
</template>

<script setup>
import { ref, onMounted } from "vue";
import { Topology } from "vue3-network-graph";
import "vue3-network-graph/style.css";

// 节点数据
const nodes = ref([
  {
    id: "core",
    label: "核心交换机",
    nodeType: "core",
    state: "normal",
    x: 0,
    y: 0,
    width: 80,
    height: 80,
  },
  {
    id: "server1",
    label: "Web 服务器",
    nodeType: "server",
    state: "normal",
    x: 300,
    y: -150,
  },
  {
    id: "db1",
    label: "数据库",
    nodeType: "database",
    state: "idle",
    x: 300,
    y: 150,
  },
  // 纯边框节点示例
  {
    id: "border-box",
    label: "",
    nodeType: "border-only",
    state: "none",
    x: -400,
    y: -200,
    width: 250,
    height: 150,
    borderWidth: 2,
    borderColor: "#00f0ff",
  },
]);

// 连线数据
const edges = ref([
  { id: "e1", from: "core", to: "server1", speed: 1.5, endMarker: "arrow" },
  {
    id: "e2",
    from: "core",
    to: "db1",
    speed: 2,
    centerText: "查询流量",
    endMarker: "arrow",
  },
]);

// 分组示例
const groups = ref([
  {
    id: "g1",
    label: "应用区",
    color: "#409eff",
    nodeIds: ["server1", "db1"],
    padding: 20,
  },
]);

// 连线模式和视图模式
const lineMode = ref("curve"); // straight | polyline | curve
const viewMode = ref("2d"); // 2d | 3d

// 配置项
const config = ref({
  selectedBorderColor: "#ffd400",
  selectedLineColor: "#ffd400",
  nodeDraggable: true,
  nodeResizable: true,
  enableZoom: true,
  enablePan: true,
  enableMarquee: true,
  showGrid: true,
  gridColor: "#1a2240",
  gridStep: 40,
  gridOpacity: 0.5,
  radialGradient: {
    startColor: "#0f1729",
    endColor: "#060a14",
  },
  showStatusDot: true,
  motionFx: true,
  maxSelectNodes: "unlimited",
  maxSelectEdges: "unlimited",
  enableZOrder: false,
});

// 组件实例引用
const topoRef = ref(null);

// 事件处理函数
const onNodeClick = (node) => {
  console.log("节点被点击:", node);
};

const onEdgeSelect = (edge) => {
  console.log("连线被选中:", edge);
};

const onSelectionChange = (selection) => {
  console.log("选中变化:", selection);
  console.log("选中节点:", selection.nodes);
  console.log("选中连线:", selection.edges);
};

const onDataChange = (payload) => {
  console.log("数据变动:", payload);
  console.log("变动摘要:", payload.summary);
};

const onEdgeCreate = (edge) => {
  console.log("新建连线:", edge);
  // 持久化新创建的连线
  edges.value = [...edges.value, edge];
};

// 方法调用示例
const handleMethods = () => {
  // 获取当前数据
  const data = topoRef.value.getData();

  // 添加节点
  topoRef.value.addNodes([
    { label: "新节点", nodeType: "server", x: 500, y: 0 },
  ]);

  // 添加连线
  topoRef.value.addEdges([{ from: "core", to: "new-node-id" }]);

  // 更新节点
  topoRef.value.updateNodes([{ id: "core", label: "更新后的名称" }]);

  // 删除选中元素
  topoRef.value.removeSelected();

  // 坐标转换
  const svgPos = topoRef.value.clientToSvg(event);
  const clientPos = topoRef.value.svgToClient(node.x, node.y);

  // 图层管理（需启用 enableZOrder）
  topoRef.value.moveToFront("node-id");
  topoRef.value.moveToBack("node-id");
  topoRef.value.moveLayerUp("node-id");
  topoRef.value.moveLayerDown("node-id");
};
</script>

<style scoped>
.topology-container {
  width: 100%;
  height: 600px;
  background: radial-gradient(ellipse at center, #0f1729 0%, #060a14 100%);
}
</style>

全局配置属性说明

radialGradient 配置

// 简单模式
radialGradient: {
  startColor: "#0f1729",
  endColor: "#060a14"
}

// 高级模式（自定义渐变中心和色带）
radialGradient: {
  cx: "50%",
  cy: "50%",
  r: "50%",
  stops: [
    { offset: "0%", color: "#0f1729", opacity: 1 },
    { offset: "60%", color: "#1e293b", opacity: 0.8 },
    { offset: "100%", color: "#060a14", opacity: 1 }
  ]
}

节点属性说明

节点类型（nodeType）

节点状态（state）

连线属性说明

连线文字格式

// 字符串简写形式
fromText: "起点文字"

// 对象完整形式
fromText: {
  text: "起点文字",      // 文字内容
  rotation: 0,          // 额外旋转角（度）
  fontSize: 10,         // 字号
  color: "#ffffff"      // 颜色
}

调用方法

通过模板 ref 调用组件暴露的方法：

<template>
  <Topology ref="topoRef" />
</template>

<script setup>
import { ref } from "vue";

const topoRef = ref(null);

// 所有方法调用示例
const methods = () => {
  // === 数据方法 ===

  // 获取当前最新数据（深拷贝）
  const { nodes, edges } = topoRef.value.getData();

  // 重置数据变动检测基线
  topoRef.value.resetDataBaseline();

  // 组件外全量替换数据集
  topoRef.value.setData({ nodes: nextNodes });

  // 删除当前选中的节点与连线（删节点时级联删除所有与该节点相连的连线）
  const removed = topoRef.value.removeSelected();

  // 添加节点（数组或单个）
  topoRef.value.addNodes([{ label: "新节点", x: 0, y: 0 }]);

  // 添加连线（数组或单个）
  topoRef.value.addEdges([{ from: "a", to: "b" }]);

  // 按 id 局部更新节点（浅合并，undefined 忽略，未知 id 跳过）
  topoRef.value.updateNodes([{ id: "node-1", label: "改名", width: 120 }]);

  // 按 id 局部更新连线
  topoRef.value.updateEdges([{ id: "edge-1", speed: 2 }]);

  // === 图层管理（需 enableZOrder: true）===

  // 上一层
  topoRef.value.moveLayerUp("node-id");

  // 下一层
  topoRef.value.moveLayerDown("node-id");

  // 最上层
  topoRef.value.moveToFront("node-id");

  // 最底层
  topoRef.value.moveToBack("node-id");

  // === 坐标转换 ===

  // 场景一：鼠标坐标 → SVG 坐标（参数可传事件对象或坐标对）
  const p1 = topoRef.value.clientToSvg(e); // 直接传事件对象
  const p2 = topoRef.value.clientToSvg(clientX, y); // 传坐标对

  // 场景二：SVG 坐标 → 屏幕坐标（输入 node.x / node.y，返回 clientX/clientY）
  const node = topoRef.value.getData().nodes[0];
  const { x, y } = topoRef.value.svgToClient(node.x, node.y);
  menu.style.left = `${x}px`;
  menu.style.top = `${y}px`;
};
</script>

事件说明

selection-change 事件详解

// 支持多种选择方式
// 1. Ctrl+ 点击多选
// 2. Ctrl+ 左键框选
// 3. 普通点击单选
// 4. 点击空白处清空

@selection-change="(sel) => {
  console.log('选中节点:', sel.nodes.map(n => n.id));
  console.log('选中连线:', sel.edges.map(e => e.id));
}"

交互操作

图层管理快捷键（需启用 enableZOrder）

交互优先级说明

• 节点与连线重叠处：点击/拖动作用于节点；连线在未被遮挡处正常点击——密集图形下节点始终可选中、可拖动
• 点击与拖动区分：左键在空白处的「点击」与「拖动」按小阈值区分（平移 4px / 框选 3px / 节点拖动 3px）：小于阈值仍视为点击（清空或切换选中），超过阈值才进入拖动

补充说明

数据同步机制

props.nodes / props.edges 为深度同步——父级整体替换数组、或就地修改字段，组件内都会跟随更新；组件内的拖拽/尺寸/增删改也会经 update:nodes、edge-create、edge-update、edge-remove 即时外发。父级把组件发出的数据原样写回不会造成循环或重复重建。

加载一整套新数据时，先更新你的 nodes / edges，再调用 setData() 清理组件内残留状态。

TypeScript 支持

import type { TopologyInstance } from "vue3-network-graph";

const topoRef = ref<TopologyInstance | null>(null);

// 类型安全的方法调用
topoRef.value?.getData();
topoRef.value?.clientToSvg(event);

坐标系说明

• 组件的节点坐标（node.x / node.y）位于 SVG 用户坐标系
• 画布的缩放与平移由 viewBox 实现，因此该坐标系与屏幕像素之间的换算随视图状态变化
• clientToSvg 使用矩阵变换，自动折算当前缩放与平移，返回的就是与 node.x / node.y 同源的坐标
• svgToClient 是它的逆变换：输入节点坐标，返回屏幕 clientX / clientY，适合与 DOM 浮层配合

许可证

MIT © 2026 vnodegit