vue-topology-flow 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# vue-topology-flow
+
+独立可复用的网络拓扑组件包（Vue 3 + TypeScript）。以 **props 输入 + 事件输出** 的受控组件形式提供，宿主项目按需配置交互、自行接入业务后端，组件本身不依赖任何具体接口。
+
+## 主要作用
+
+一套代码同时满足两种拓扑场景，作为独立 npm 包提供给任意 Vue 3 项目使用：
+
+1. **自动拓扑（auto）**：将网络扫描结果渲染为拓扑图，支持多种布局算法（含 ELK 分层布局）、布局切换、设备绑定与详情查看，适用于"扫描出来的网络结构可视化"。
+2. **手动绘图（manual）**：基于 X6 的流程图画布，左侧图形面板拖拽建图，支持图标节点 / 文本节点 / 分组容器 / 连线编辑，适用于"人工绘制网络拓扑、流程图"。
+
+## 功能一览
+
+### 自动拓扑
+- 扫描设备/链路数据渲染，未解析节点单独归类
+- 多布局算法与自定义布局，布局保存与恢复
+- 设备绑定/解绑、设备详情弹窗、搜索定位
+- 视图操作：预览、导出（PNG/SVG/JSON）、生成缩略图
+
+### 手动绘图
+- 左侧分组面板拖拽建节点：基础流程图形状、文本（矩形/圆形）、系统设计图、PNG/SVG 图标、分组容器
+- 连线：端口吸附、正交/曲线/直线/弧线、箭头、虚实、线宽、颜色、标签编辑
+- 分组容器：背景/边框/头部样式设置、重命名、解散
+- 画布操作：缩放、平移、框选、撤销/重做、网格、快捷键、清空、导出
+- 预览模式（只读查看）
+
+### 可配置交互（对宿主开放）
+- **右键菜单**：内置项（查看详情/设置/重命名/关联设备/线条编辑/断开连接/删除等）可隐藏、覆盖、追加自定义项，或完全替换自绘
+- **点击行为**：按元素类别（节点/连线/容器/文本）分别配置 `select`（选中）/ `detail`（详情）/ `edit`（编辑弹窗）/ `none`（仅事件）
+- **工具条**：保存/缩略图/预览/导出按钮可分别隐藏
+- **事件输出**：`node-click` / `edge-click` / `group-click` / `text-click` / `node-dblclick` / `blank-click` / `context-menu` / `save` / `change` / `bind` / `unbind` 等，业务逻辑由宿主处理
+- 菜单组装与点击行为解析抽离为独立纯函数模块（`menu.ts` / `interactions.ts`），宿主可 import 后动态扩展
+
+## 技术栈
+
+Vue 3 `<script setup>` + TypeScript · Vite 6 · AntV X6 3.x · elkjs · element-plus（peer）
+
+## 安装与使用
+
+```bash
+npm install vue-topology-flow
+# peer: vue ^3.3 / element-plus >= 2.4 / @antv/x6 ^3.1 / @element-plus/icons-vue ^2.3
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TopologyGraph, type TopologyDocument, type TopologyEventTarget } from 'vue-topology-flow'
+import 'vue-topology-flow/index.css'
+
+const data = ref<TopologyDocument>(/* 拓扑数据 */)
+const onSave = (doc: TopologyDocument) => { /* 宿主保存到后端 */ }
+const onNodeClick = (t: TopologyEventTarget) => { /* 宿主业务 */ }
+</script>
+
+<template>
+  <TopologyGraph mode="manual" :data="data" @save="onSave" @node-click="onNodeClick" />
+</template>
+```
+
+也可通过 `ref` 持有 `TopologyHandle` 调用 `getData()` / `save()` / `fitView()` / `exportFile()`。
+
+完整演示与全部 props/events 配置见 `src/App.vue`（`npm run dev` 启动演示站）。
+
+## 开发
+
+```bash
+npm install
+npm run dev          # 演示站 (Vite)
+npm run typecheck    # vue-tsc 类型检查
+npm run build        # lib 构建 (dist/, 含 .d.ts 声明)
+npm run build:demo   # 演示站构建
+```
+
+## 目录结构
+
+```
+src/components/topology/
+├── TopologyGraph.vue      # 统一入口 (mode=auto|manual)
+├── types.ts               # 对外类型: 文档/事件目标/菜单/点击行为/工具条配置
+├── index.ts               # 包出口 (组件 + 类型 + 交互配置函数)
+├── auto/                  # 自动拓扑: 渲染/布局(ELK)/数据/样式
+├── manual/                # 手动绘图:
+│   ├── ManualTopology.vue # 画布 + 面板 + 弹窗
+│   ├── menu.ts            # 右键菜单组装 (纯函数, 可扩展)
+│   ├── interactions.ts    # 元素分类与点击行为解析 (纯函数)
+│   └── data/              # 面板图形配置
+└── shared/                # 设备选择抽屉/详情弹窗
+```
+
+## 设计约定
+
+- 组件不内置任何业务接口请求；数据进、事件出，业务归属宿主
+- 导出文件（PNG/SVG）由组件本地生成，不依赖后端
+- 第三方集成时，X6 与 element-plus 由宿主提供（peerDependencies）