tree-graph-vue

Vue 3 + TypeScript 的树形关系图组件库，用于展示和编辑 JSON 树结构，支持多父连线、导入导出、缩放和平移。

安装

npm install tree-graph-vue-zy

在应用入口或使用组件的地方引入样式：

import 'tree-graph-vue-zy/style.css'

文档

• 设计文档：docs/vue3-tree-graph-design.md
• 本地开发服务端口复盘：docs/dev-server-loopback-postmortem.md
• 原始 HTML 参考实现：docs/legacy-tree-graph-editor.html
• 组件源码：src/components/tree-graph/
• 示例入口：src/App.vue

组件封装情况

当前树图功能封装为 4 个 Vue 组件：

• TreeGraphEditor.vue：完整编辑器容器，负责编辑状态、选择状态、导入导出、节点和连线操作。
• TreeGraphView.vue：树图展示组件，负责 SVG 渲染、节点/连线展示、节点点击、按钮缩放、Ctrl+滚轮缩放和空白画布拖动。
• TreeToolbar.vue：编辑工具栏，提供新增、编辑、删除节点、添加/删除连线、导入导出和重置入口。
• NodeEditDialog.vue：节点新增/重命名弹窗。

配套逻辑：

• types/treeGraphTypes.ts：树节点、配置、布局和导出 payload 类型。
• composables/useTreeGraphLayout.ts：布局计算和连线路径计算。
• composables/useTreeGraphActions.ts：节点与附加连线的增删改纯函数。
• utils/treeGraphData.ts：默认数据、克隆、规范化、查找节点等工具函数。

数据结构

组件以 JSON 树作为核心数据结构：

export interface TreeGraphNode {
  id: string
  name: string
  children?: TreeGraphNode[]
  multiParentIds?: string[]
  isRoot?: boolean
}

• children 表示主树父子关系。
• multiParentIds 表示附加父关系，用于一个节点关联多个父节点的场景。
• 所有节点都应有稳定的 id，不要依赖 name 建立关系。

调用示例

默认查看模式用法，组件右上角会显示“编辑”按钮：

<script setup lang="ts">
import { ref } from 'vue'
import TreeGraphEditor from 'tree-graph-vue-zy'
import type { TreeGraphNode } from 'tree-graph-vue-zy'
import 'tree-graph-vue-zy/style.css'

const treeData = ref<TreeGraphNode>({
  id: 'root',
  name: '根节点',
  isRoot: true,
  children: [
    { id: 'child-a', name: '子节点 A', children: [] },
    { id: 'child-b', name: '子节点 B', children: [] },
  ],
})
</script>

<template>
  <TreeGraphEditor v-model:data="treeData" />
</template>

初始显示编辑工具栏：

<template>
  <TreeGraphEditor v-model:data="treeData" show-toolbar />
</template>

传入自定义配置：

<script setup lang="ts">
import { ref } from 'vue'
import TreeGraphEditor from 'tree-graph-vue-zy'
import type { TreeGraphConfig, TreeGraphNode } from 'tree-graph-vue-zy'
import 'tree-graph-vue-zy/style.css'

const treeData = ref<TreeGraphNode>({
  id: 'root',
  name: '根节点',
  isRoot: true,
  children: [],
})

const graphConfig: Partial<TreeGraphConfig> = {
  nodeWidth: 140,
  nodeHeight: 56,
  levelGap: 120,
}
</script>

<template>
  <TreeGraphEditor
    v-model:data="treeData"
    :config="graphConfig"
    show-toolbar
    @change="(nextData) => console.log(nextData)"
  />
</template>

只读展示用法：

<script setup lang="ts">
import { TreeGraphView } from 'tree-graph-vue-zy'
import type { TreeGraphNode } from 'tree-graph-vue-zy'
import 'tree-graph-vue-zy/style.css'

defineProps<{
  data: TreeGraphNode
}>()
</script>

<template>
  <TreeGraphView :data="data" mode="view" />
</template>

交互说明：

• 点击 +、-、⟲ 控制缩放和重置视图。
• 按住 Ctrl 后滚动鼠标滚轮可缩放画布。
• 在空白画布区域按住鼠标左键拖动可平移画布。

开发命令

npm install
npm run dev
npm run typecheck
npm run build
npm run pack:dry

发布检查

发布前建议依次运行：

npm run build
npm pack --dry-run

确认产物列表只包含 dist/、README.md 和必要的包元数据后，再执行：

npm publish

Git 管理建议

• 设计、迁移和组件说明统一放在 docs/。
• 组件源码集中放在 src/components/tree-graph/。
• 如果后续拆出更多设计文档，建议按主题命名，例如 docs/import-export.md、docs/layout.md。