概览

relation-graph 是一个跨平台的图可视化与编辑库，专为构建知识图谱、组织结构图、网络拓扑以及其他基于关系的数据可视化而设计。该系统提供了一个与框架无关的核心，并为 Vue 2、Vue 3、React、Svelte 和 Web Components 提供了专门的适配器。

本文档对系统架构、核心组件以及不同平台包如何共享通用功能进行高层介绍。有关各个子系统的具体实现细节，请参阅：

• 核心架构和类层级：核心架构
• 数据管理：数据管理系统
• 布局算法：布局系统
• 渲染管线：渲染系统
• 用户交互：用户交互与事件

目的与能力

该库使开发者能够：

• 可视化复杂关系：使用节点和线/边来展示实体之间的关系
• 应用自动布局：使用力导向、树形、环形和混合算法
• 与图交互：通过平移、缩放、节点拖拽和选择进行操作
• 编辑图结构：以交互方式创建、更新和删除节点与连线
• 自定义渲染：使用特定框架的插槽系统来自定义节点和连线
• 处理大型数据集：通过视口裁剪和基于 Canvas 的性能模式提升表现

系统架构

多平台包结构

该系统以五个独立的 npm 包形式分发，每个包面向特定的 JavaScript 框架。所有包共享相同的核心业务逻辑，但提供框架特定的 UI 组件和响应式数据集成。

graph TB
    subgraph "已发布的 npm 包"
        Vue2["@relation-graph/vue2
Vue 2.x 包装器"]
        Vue3["@relation-graph/vue
Vue 3.x 包装器"]
        React["@relation-graph/react
React 包装器"]
        Svelte["@relation-graph/svelte
Svelte 包装器"]
        WebComp["@relation-graph/web-components
与框架无关"]
    end

    subgraph "共享核心层"
        Core["RelationGraphCore
packages/relation-graph-models/"]
        Types["类型定义
packages/types.ts"]
        Layouts["布局引擎
packages/relation-graph-models/layouters/"]
        Utils["工具与数据提供器
packages/relation-graph-models/"]
    end

    Vue2 --> Core
    Vue3 --> Core
    React --> Core
    Svelte --> Core
    WebComp --> Core

    Core --> Types
    Core --> Layouts
    Core --> Utils

包位置：

• Vue 2 包：platforms/vue2/
• Vue 3 包：platforms/vue3/
• React 包：platforms/react/
• Svelte 包：platforms/svelte/
• Web Components 包：platforms/web-components/

核心实例架构

RelationGraphCore 类通过渐进增强模式构建，大约有 20 个类通过线性继承各自添加特定能力。这使得功能可以模块化组织，同时保持单一且内聚的 API。

graph LR
    Base["RelationGraphBase
事件系统"]
    View["RelationGraphWith1View
DOM 与坐标"]
    Data["RelationGraphWith2Data
数据管理"]
    Options["RelationGraphWith3Options1Update
配置"]
    Line["RelationGraphWith4Line
连线渲染"]
    Zoom["RelationGraphWith5Zoom
缩放控制"]
    Layout["RelationGraphWith6Layout
布局算法"]
    Event["RelationGraphWith7Event
用户交互"]
    Editing["RelationGraphWith91Editing
编辑模式"]
    API["RelationGraphWith99API
公共 API"]
    Final["RelationGraphCore"]

    Base --> View --> Data --> Options --> Line
    Line --> Zoom --> Layout --> Event --> Editing
    Editing --> API --> Final

链中的每个类都会添加特定功能：

• RelationGraphBase：事件发射和 UUID 生成
• RelationGraphWith1View：canvas、viewport 和 client 空间之间的坐标变换
• RelationGraphWith2Data：响应式数据初始化和 CRUD 操作
• RelationGraphWith4Line：连线路径生成和渲染计算
• RelationGraphWith7Event：鼠标和触摸事件处理
• RelationGraphWith91Editing：节点选择、调整大小和连线编辑

数据模型

系统使用一个转换流水线，将用户提供的 JSON 数据转换为在运行时增强过的对象，以便于渲染和交互。

核心数据类型

类型	用途	位置
JsonNode	节点的用户输入格式	packages/types.ts:206-241
JsonLine	连线的用户输入格式	packages/types.ts:296-340
RGNode	带有布局数据的运行时节点	packages/types.ts:245-276
RGLine	运行时连线对象	packages/types.ts:356-359
RGLink	将连线连接到节点的派生对象	packages/types.ts:372-381
RGFakeLine	端点不是节点的连线	packages/types.ts:347-351

类型关系

graph TD
    subgraph "用户输入类型"
        JsonNode["JsonNode
{id, text, x, y, ...}"]
        JsonLine["JsonLine
{from, to, text, ...}"]
    end

    subgraph "运行时类型"
        RGNode["RGNode
+ lot: 布局数据
+ rgShouldRender
+ el_W, el_H"]
        RGLine["RGLine
+ isReverse"]
        RGLink["RGLink
+ fromNode
+ toNode
+ currentLineIndex"]
    end

    subgraph "内部数据结构"
        RGGraphData["RGGraphData
{nodes: RGNode[]
normalLines: RGLine[]
fakeLines: RGFakeLine[]}"]
    end

    JsonNode -->|"json2Node()"| RGNode
    JsonLine -->|"json2Line()"| RGLine
    RGLine -->|"与节点关联"| RGLink
    RGNode --> RGGraphData
    RGLine --> RGGraphData

数据转换函数：

• 节点转换：packages/relation-graph-models/data/RGNodeDataUtils.ts
• 连线转换：packages/relation-graph-models/data/RGLineDataUtils.ts:3-86

组件组织

渲染系统由特定框架的 UI 组件组成，这些组件将业务逻辑委托给共享的核心实例。

主要组件

graph TB
    subgraph "用户应用"
        App["应用代码"]
    end

    subgraph "顶层组件"
        RG["RelationGraph
主入口组件
创建 RelationGraphCore"]
    end

    subgraph "UI 布局组件"
        RGUI["RelationGraphUI
编排布局"]
        Canvas["RGCanvas
SVG/Canvas 渲染表面"]
        Toolbar["RGToolBar
缩放/布局控制"]
        MiniView["RGMiniView
概览导航器"]
    end

    subgraph "内容组件"
        Node["RGNode
节点渲染器"]
        LinePath["RGLinePath
连线路径 SVG"]
        LineText["RGLineText
连线标签"]
        ConnectTarget["RGConnectTarget
连接点"]
    end

    subgraph "编辑组件"
        EditNode["RGEditingNodeController
选择 UI"]
        EditLine["RGEditingLineController
连线编辑 UI"]
        RefLines["RGReferenceLines
对齐参考线"]
    end

    App --> RG
    RG --> RGUI
    RGUI --> Canvas
    RGUI --> Toolbar
    RGUI --> MiniView
    Canvas --> Node
    Canvas --> LinePath
    Canvas --> LineText
    Node --> ConnectTarget
    RGUI --> EditNode
    RGUI --> EditLine
    RGUI --> RefLines

组件实现：

• Vue 组件：platforms/vue3/src/components/, platforms/vue2/src/components/
• React 组件：platforms/react/src/components/
• Svelte 组件：platforms/svelte/src/components/

配置与选项

系统使用两层配置结构：

类型	用途	可变性
RGOptions	用户提供的部分配置	部分
RGOptionsInited	带默认值的完整配置	初始化后不可变
RGOptionsFull	运行时状态 + 配置	运行时可变

关键配置类别：

• 布局选项：layout.layoutName、layout.layoutDirection、特定布局参数
• 视觉默认值：defaultNodeColor、defaultLineShape、defaultLineWidth
• 交互设置：disableDragNode、wheelEventAction、dragEventAction
• 性能模式：performanceMode（启用视口裁剪）

布局系统

该库提供多种自动布局算法，每种都实现了 RGLayout 接口：

布局类	布局名称	使用场景
RGTreeLayout	tree	分层树结构
RGForceLayout	force	基于物理的仿真
RGCenterLayout	center	围绕中心节点的径向布局
RGCircleLayout	circle	圆形排列
RGFixedLayout	fixed	无自动定位
RGSmartTreeLayout	smart-tree	树形 + 力导向混合
RGIOTreeLayout	io-tree	输入输出双向树
RGFolderLayout	folder	文件系统层级

所有布局类都位于：packages/relation-graph-models/layouters/

响应式数据集成

每个框架包都包含一个专门的数据提供器，用于桥接框架的响应式系统和核心的数据模型：

数据提供器	框架	位置
RGDataProvider4Vue2	Vue 2	使用 Vue.set() 实现响应式
RGDataProvider4Vue3	Vue 3	使用 ref() 和 reactive()
RGDataProvider4React	React	使用 state hooks 和 setState
RGDataProvider4Svelte	Svelte	使用 writable stores

数据提供器抽象了各框架在追踪对象和数组变更方式上的差异，使核心能够保持与框架无关，同时仍然适当地触发 UI 更新。

设置方法：

• Vue 2：ai-prompt/wiki/relation-graph-instance-architect/RelationGraphInstance.md:412-431
• Vue 3：ai-prompt/wiki/relation-graph-instance-architect/RelationGraphInstance.md:433-455
• React：ai-prompt/wiki/relation-graph-instance-architect/RelationGraphInstance.md:457-470
• Svelte：ai-prompt/wiki/relation-graph-instance-architect/RelationGraphInstance.md:472-485

API 表面

RelationGraphInstance（RelationGraphCore 的别名）按能力公开了组织好的方法：

数据操作

• 添加：addNode()、addNodes()、addLine()、addLines()
• 删除：removeNode()、removeNodeById()、removeLine()、removeLineById()
• 更新：updateNode()、updateLine()、updateNodeData()、updateLineData()
• 查询：getNodeById()、getLineById()、getNodes()、getLines()、getLinks()

图分析

• 关系：getRelatedLinesByNode()、getNodeRelatedNodes()、getNodeIncomingNodes()
• 网络分析：getNetworkNodesByNode()、getDescendantNodes()
• 空间查询：getNodesRectBox()、getNodesCenter()、getNodesInSelectionView()

布局控制

• 触发：doLayout()、refresh()、resetViewSize()
• 动画：zoomToFit()、focusOnNode()、focusOnLink()

交互

• 编辑模式：startEditingNodes()、startEditingLine()、stopEditingNodes()
• 创建：startCreatingNodePlot()、startCreatingLinePlot()
• 导航：setZoom()、zoomIn()、zoomOut()、moveCanvasTo()

完整 API 参考：API Reference

性能注意事项

系统包含多项用于处理大型图的优化：

1. 视口裁剪：启用 performanceMode 时，仅渲染可见视口内的节点和连线
2. EasyView 模式：在低缩放级别（< 40%）时自动回退到 Canvas 2D 渲染
3. 批量更新：基于 requestAnimationFrame 的更新批处理可防止冗余渲染
4. 惰性计算：仅为可见连线计算路径
5. MiniView 优化：概览图使用简化的 canvas 渲染

有关性能模式的详细信息：Performance Mode & EasyView

文件结构概览

relation-graph-vip/
├── packages/
│   ├── types.ts                           # 核心类型定义
│   └── relation-graph-models/
│       ├── models/
│       │   ├── RelationGraphBase.ts       # 带事件的基类
│       │   ├── RelationGraphWith*.ts      # 渐进增强类
│       │   └── RelationGraphCore.ts       # 最终组装的类
│       ├── layouters/
│       │   ├── RGForceLayout.ts          # 力导向算法
│       │   ├── RGTreeLayout.ts           # 树形布局
│       │   └── ...                        # 其他布局实现
│       ├── data/
│       │   ├── RGNodeDataUtils.ts        # 节点数据转换
│       │   └── RGLineDataUtils.ts        # 连线数据转换
│       └── utils/
│           └── line/RGLinePath.ts        # 连线路径生成
├── platforms/
│   ├── vue2/                              # Vue 2 包装包
│   ├── vue3/                              # Vue 3 包装包
│   ├── react/                             # React 包装包
│   ├── svelte/                            # Svelte 包装包
│   └── web-components/                    # Web Components 包
└── package.json                           # Monorepo 根目录

每个平台包都包含：

• src/components/：特定框架的 UI 组件
• src/core4react/（或类似目录）：数据提供器实现
• package.json：包元数据和依赖项

快速开始

要在你的项目中使用 relation-graph：

1. 为你的框架安装合适的包
2. 导入主组件和类型
3. 通过组件创建图实例
4. 使用 setJsonData() 或 addNodes()/addLines() 设置初始数据
5. 配置布局和交互选项
6. 通过 slots/render props 自定义节点/连线渲染

有关详细设置说明，请参阅：Getting Started

有关特定平台的集成细节：

• Vue：Vue 2 & Vue 3 Integration
• React：React Integration
• Svelte：Svelte Integration
• Web Components：Web Components