JavaScript is required
relation-graph 图展示 & 图编辑
登录 English GitHub

平台集成

本文档概述 relation-graph 的多平台架构。该系统通过单一的框架无关核心与轻量的各平台适配层，支持 Vue 2、Vue 3、React、Svelte 以及 Web Components。该设计在充分利用各框架原生响应式系统的同时，确保所有平台上的功能一致性。

关于特定框架的详细集成信息，请参见：

关于核心架构详情，请参见 核心架构。关于构建与分发流程，请参见 构建系统与分发。

多平台设计

Relation-graph 通过将图谱逻辑与框架特定的渲染分离来实现跨平台兼容。relation-graph-models 包含所有核心能力，而各平台包提供集成层。

架构分层

系统架构概览

graph TB
    subgraph PlatformLayer["平台层"]
        Vue2["@relation-graph/vue2
Vue 2 组件"]
        Vue3["@relation-graph/vue
Vue 3 组件"]
        React["@relation-graph/react
React 组件"]
        Svelte["@relation-graph/svelte
Svelte 组件"]
        WC["@relation-graph/web-components
Web Components"]
    end
    
    subgraph IntegrationLayer["集成层"]
        DataProviders["框架特定数据提供器
RGDataProvider4Vue2/Vue3/React/Svelte"]
        Hooks["框架 Hooks 与 Context
useRelationGraph, RGProvider"]
    end
    
    subgraph CoreLayer["核心库 - relation-graph-models"]
        RGCore["RelationGraphCore
RelationGraphFinal"]
        DataModel["数据管理
RGDataProvider, RGNode, RGLine"]
        Layouts["布局算法
RGTreeLayout, RGForceLayout"]
        Events["事件系统
RelationGraphWith7Event"]
    end
    
    Vue2 --> DataProviders
    Vue3 --> DataProviders
    React --> DataProviders
    Svelte --> DataProviders
    WC --> DataProviders
    
    DataProviders --> Hooks
    Hooks --> RGCore
    
    RGCore --> DataModel
    RGCore --> Layouts
    RGCore --> Events

核心库结构

relation-graph-models 包提供：

组件 用途
RelationGraphCore / RelationGraphFinal 具备全部能力的主图实例类
RGDataProvider 用于响应式数据集成的抽象基类
布局类 RGTreeLayout, RGForceLayout, RGCenterLayout, 等
类型定义 RGNode, RGLine, RGLink, RGOptions
工具模块 RGGraphMath, RGNodesAnalytic, 路径生成器

数据提供器系统

数据提供器系统将框架无关的核心与各平台的响应式系统连接起来。RelationGraphWith2Data 为每个框架提供集成方法，用于实例化相应的 RGDataProvider 子类。

提供器架构

数据提供器集成流程

graph LR
    subgraph CoreInit["RelationGraphWith2Data 中的初始化"]
        SetVue2["setReactiveData4Vue2()"]
        SetVue3["setReactiveData4Vue3()"]
        SetReact["setReactiveData4React()"]
        SetSvelte["setReactiveData4Svelte()"]
    end
    
    subgraph ProviderInstances["提供器实例"]
        Vue2Prov["RGDataProvider4Vue2"]
        Vue3Prov["RGDataProvider4Vue3"]
        ReactProv["RGDataProvider4React"]
        SvelteProv["RGDataProvider4Svelte"]
    end
    
    subgraph ReactivitySystems["框架响应式机制"]
        Vue2React["Vue.set / Vue.delete"]
        Vue3React["reactive() / ref()"]
        ReactState["setState callbacks"]
        SvelteStores["writable() stores"]
    end
    
    SetVue2 --> Vue2Prov
    SetVue3 --> Vue3Prov
    SetReact --> ReactProv
    SetSvelte --> SvelteProv
    
    Vue2Prov --> Vue2React
    Vue3Prov --> Vue3React
    ReactProv --> ReactState
    SvelteProv --> SvelteStores

RGDataProvider 接口

所有数据提供器都实现 RGDataProvider 抽象类，该类定义了：

方法 描述
updateOptions(options) 更新图配置
addNodes(nodes) 向图中添加节点
removeNodeById(nodeIds) 按 ID 移除节点
updateNode(nodeId, updates) 更新节点属性
addLines(lines) 添加连线
removeLine(lineId) 移除一条连线
dataUpdated() 触发视图更新（框架特定）

dataUpdated() 方法是各提供器与其框架响应式系统集成的关键点，会调用相应的更新机制。

平台特定集成

每个平台都提供量身定制的集成方式，以利用框架特定的模式与惯用法。下面是各平台的概要；详细信息请参见链接的章节。

平台对比

平台 包名 响应式系统 Context/Provider 模式 主要 API
Vue 2 @relation-graph/vue2 Vue.set() / Vue.delete() provide() / inject() Options API, Slots
Vue 3 @relation-graph/vue reactive() / ref() provide() / inject() Composition API, useRelationGraph()
React @relation-graph/react setState callbacks Context API useRelationGraph() hook, RGProvider
Svelte @relation-graph/svelte writable() stores setContext() / getContext() RGHooks collection
Web Components @relation-graph/web-components 基于事件的更新 N/A（Web 标准） 自定义元素属性

Vue 集成（Vue 2 与 Vue 3）

Vue 集成提供 RelationGraph.vue 组件，完整支持 slots、v-model 以及 Vue 的响应式系统：

  • Vue 2：使用 RGDataProvider4Vue2 并通过 Vue.set() 实现响应式；通过 provide/inject 访问实例；使用 graphStoreMixin 进行状态管理
  • Vue 3：使用 RGDataProvider4Vue3 并通过 reactive() stores；基于 Composition API 的 useRelationGraph() hook；以及 RGProvider 包装组件

两个版本导出相同的组件层级与工具。详情请参见 Vue 2 与 Vue 3 集成。

React 集成

React 集成提供基于 hooks 的 API，并通过 useRelationGraph() hook 访问图实例：

  • 使用 RGDataProvider4React 并通过 setState 回调触发重渲染
  • 基于 Context 的架构，包含 RelationGraphStoreContext 与 RGProvider
  • 组件使用 useImperativeHandle 暴露命令式 API
  • 完整的 TypeScript 支持，包含 RelationGraphComponent 类型

关于 hook 用法与 context 设置的详细内容，请参见 React 集成。

Svelte 集成

Svelte 集成使用 stores 与 context 进行响应式数据管理：

  • 使用 RGDataProvider4Svelte 并通过 writable() stores
  • RGHooks collection 提供常见操作的辅助函数
  • 组件使用 getContext() 访问图实例
  • stores 会在 Svelte 组件中自动触发响应式更新

关于 store 结构与使用模式，请参见 Svelte 集成。

Web Components

Web Components 构建由 Svelte 实现生成，提供框架无关的自定义元素：

  • 使用 Svelte 的 customElement: true 编译选项构建
  • 注册为 <relation-graph> 自定义元素
  • 可在任何 JavaScript 环境中访问
  • 使用标准 DOM 事件与 attributes 作为 API

关于构建流程与使用方式，请参见 Web Components。

共享组件结构

所有平台都会导出一组一致的组件，并根据各自框架的约定进行适配。核心组件层级在各平台之间保持一致。

导出组件

组件导出结构

graph TB
    subgraph MainComponents["主要组件"]
        RG["RelationGraph
主图组件"]
        RL["RelationLinker
仅连线显示"]
    end
    
    subgraph Primitives["基础组件"]
        FakeNode["RGFakeNode
临时节点预览"]
        LinePath["RGLinePath
SVG 路径渲染"]
        LineText["RGLineText
连线标签文字"]
        NodeExpandHolder["RGNodeExpandHolder
展开/折叠手柄"]
    end
    
    subgraph UIWidgets["UI 小组件"]
        ToolBar["RGToolBar
缩放/布局控制"]
        MiniToolBar["RGMiniToolBar
紧凑工具栏"]
        MiniView["RGMiniView
小地图导航"]
        Background["RGBackground
网格/图案背景"]
        Watermark["RGWatermark
版权/水印"]
        DebugView["RGDebugView
调试信息"]
    end
    
    subgraph EditingComponents["编辑组件"]
        EditNode["RGEditingNodeController
节点选择/缩放"]
        EditLine["RGEditingLineController
连线顶点编辑"]
        EditConnect["RGEditingConnectController
连线目标定位"]
        EditResize["RGEditingResize
缩放手柄"]
        NearNodeWidget["RGEditingNearNodeWidget
附近节点提示"]
        ConnectPoints["RGEditingConnectPoints
连接点"]
        ReferenceLine["RGEditingReferenceLine
对齐辅助线"]
        ConnectSource["RGConnectSource
连接源"]
        ConnectTarget["RGConnectTarget
连接目标"]
    end
    
    subgraph ProviderContext["Provider/Context"]
        Provider["RGProvider
Context provider 包装器"]
    end
    
    RG --> Primitives
    RG --> UIWidgets
    RG --> EditingComponents
    RL --> LinePath
    RL --> LineText

工具导出

所有平台还会导出共享的工具模块与布局类：

导出项 内容
RGLayouts BaseLayout, BidirectionalTreeLayout, CenterLayout, CircleLayout, FixedLayout, ForceLayout, RGFolderLayout
RGUtils RGOptionsDataUtils, RGLineDataUtils, RGNodeDataUtils, RGGraphMath, RGNodesAnalyticUtils, RGEffectUtils
RelationGraphCore 核心图实例类（用于高级用法）
类型定义 从 relation-graph-models 导出的完整 TypeScript types

框架适配模式

方面 Vue 2/3 React Svelte
实例访问 inject('graphInstance') useContext(GraphContext) getContext('graph')
事件处理 @event="handler" onEvent={handler} on:event={handler}
Slots/Children <slot name="x"> props.children / render props <slot name="x">
条件渲染 v-if, v-show {condition && <C/>} {#if condition}
列表渲染 v-for .map() {#each items}
双向绑定 v-model Controlled components bind:value

构建与分发

该库提供多种分发策略，以支持不同的使用方式。

包结构

graph LR
    subgraph "源代码"
        Models["relation-graph-models
TypeScript 核心"]
        Vue2Src["platforms/vue2"]
        Vue3Src["platforms/vue3"]
        ReactSrc["platforms/react"]
        SvelteSrc["platforms/svelte"]
    end
    
    subgraph "构建产物"
        LibVue2["lib/vue2/
UMD + ESM"]
        LibVue3["lib/vue3/
UMD + ESM"]
        LibReact["lib/react/
UMD + ESM"]
        LibSvelte["lib/svelte/
UMD + ESM"]
    end
    
    subgraph "NPM 包"
        MainPkg["relation-graph@3.0.0
所有框架"]
        Vue2Pkg["relation-graph-vue2@2.2.11"]
        Vue3Pkg["relation-graph-vue3@2.2.11"]
        ReactPkg["relation-graph-react@2.2.11"]
    end
    
    Models --> LibVue2
    Vue2Src --> LibVue2
    Vue3Src --> LibVue3
    ReactSrc --> LibReact
    SvelteSrc --> LibSvelte
    
    LibVue2 --> MainPkg
    LibVue3 --> MainPkg
    LibReact --> MainPkg
    LibSvelte --> MainPkg
    
    LibVue2 --> Vue2Pkg
    LibVue3 --> Vue3Pkg
    LibReact --> ReactPkg
    
    style MainPkg fill:#f9f9f9

NPM 包导出

主包（relation-graph@3.0.0）使用**子路径导出（subpath exports）**来选择框架：

{
  "exports": {
    ".": { /* 默认使用 Vue 2 */ },
    "./react": { "import": "./lib/react/relation-graph.mjs" },
    "./vue2": { "import": "./lib/vue2/relation-graph.mjs" },
    "./vue3": { "import": "./lib/vue3/relation-graph.mjs" },
    "./svelte": { "import": "./lib/svelte/relation-graph.mjs" }
  }
}

框架特定包提供直接导入：

  • relation-graph-vue2@2.2.11 - 仅 Vue 2
  • relation-graph-vue3@2.2.11 - 仅 Vue 3
  • relation-graph-react@2.2.11 - 仅 React

使用方式

单体包：

// Vue 3
import { RelationGraph } from 'relation-graph/vue3'

// React
import { RelationGraph } from 'relation-graph/react'

框架特定包：

// Vue 2
import { RelationGraph } from 'relation-graph-vue2'

// React
import { RelationGraph } from 'relation-graph-react'

CDN（UMD）：

<script src="https://unpkg.com/relation-graph@3.0.0/lib/vue2/relation-graph.umd.js"></script>

性能模式集成

所有平台集成都支持性能模式，该模式会切换为 Canvas/WebGL 渲染以应对大规模图谱。

性能模式检测

数据提供器会检查 options.performanceMode 与 options.showEasyView：

if (performanceMode && !showEasyView) {
  // 跳过节点/连线的响应式更新
  // Canvas 渲染负责可视化
}

当性能模式启用时：

  • 节点/连线的响应式 stores 不会更新（以避免开销）
  • 使用 RGEasyView 的基于 Canvas 的渲染
  • 只有 options 更新会触发响应式变化

这确保即使在拥有数千个节点时也能保持流畅交互，因为响应式系统只跟踪配置，而不跟踪单个图元素。