快速开始

目的与范围

本页提供 relation-graph 在所有受支持平台（Vue 2、Vue 3、React、Svelte 和 Web Components）上的安装和基本使用说明。内容涵盖包安装、基础组件集成以及核心使用模式。有关内部架构的详细信息，请参见核心架构。有关配置选项，请参见配置与选项。有关 API 方法，请参见 API 参考。

安装

relation-graph 以针对每个受支持框架分别提供的 npm 包形式发布。所有包共享相同的核心逻辑，但提供特定于框架的包装器。

框架	包名	版本	安装命令
Vue 2	`@relation-graph/vue2`	3.0.3	`npm install @relation-graph/vue2`
Vue 3	`@relation-graph/vue`	3.0.3	`npm install @relation-graph/vue`
React	`@relation-graph/react`	3.0.3	`npm install @relation-graph/react`
Svelte	`@relation-graph/svelte`	3.0.3	`npm install @relation-graph/svelte`
Web Components	`@relation-graph/web-components`	3.0.3	`npm install @relation-graph/web-components`

包架构概览

下图说明了特定平台的包与共享核心之间的关系：

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 "共享核心 (内部)"
        RGCore["RelationGraphCore
与框架无关的业务逻辑"]
        DataProvider["RGDataProvider
响应式数据抽象"]
        Types["类型定义
RGNode, RGLine, RGOptions"]
    end

    Vue2 --> RGCore
    Vue3 --> RGCore
    React --> RGCore
    Svelte --> RGCore
    WebComp --> RGCore

    RGCore --> DataProvider
    RGCore --> Types
    DataProvider --> Types

按平台划分的基本用法

Vue 2

Vue 2 的使用方式是导入 RelationGraph 组件，并在模板中使用它，通过 v-bind 传递选项，并使用 @ 语法注册事件监听器。

组件结构：

入口组件：RelationGraph，来自 packages/platforms/vue2/src/core4vue/RelationGraph.vue:1-184
UI 组件：RelationGraphUI，来自 packages/platforms/vue2/src/core4vue/RelationGraphUI.vue:1-136
使用 RGProvider 进行实例管理，位置见 packages/platforms/vue2/src/core4vue/RelationGraph.vue:2-27

关键集成点：

模板:
  <RelationGraph :options="graphOptions" @onNodeClick="handleNodeClick">
    <!-- 通过 #node 插槽进行自定义节点渲染 -->
    <template #node="{ node }">
      <!-- 自定义节点内容 -->
    </template>
  </RelationGraph>

脚本:
  - 导入 RelationGraph 组件
  - 定义 options 对象（RGOptions 类型）
  - 使用 ref.getInstance() 访问 RelationGraphCore 实例
  - 使用 @ 语法注册事件处理器

实例访问模式： 该组件通过模板 ref 暴露 getInstance() 方法。此方法返回底层的 RelationGraphCore 实例，但会显示来自 packages/platforms/vue2/src/core4vue/RelationGraph.vue:170-172 的警告信息，因为 Vue 2 使用了响应式数据集成，应该通过数据提供者模式来访问。详见响应式数据集成。

Vue 3

Vue 3 的使用方式利用了 Composition API 和 setup script 语法，并改进了 TypeScript 支持。

组件结构：

入口组件：RelationGraph，来自 packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:1-76
UI 组件：RelationGraphUI，来自 packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraphUI.vue:1-97
使用 useRelationGraph 组合式函数创建实例

关键集成点：

模板:
  <RelationGraph :options="graphOptions" @onNodeClick="handleNodeClick">
    <!-- 自定义渲染插槽: #node, #line, #canvas, #canvas-above, #background -->
  </RelationGraph>

Script Setup:
  - 从 '@relation-graph/vue' 导入 RelationGraph
  - 将 options 定义为 ref 或 reactive 对象
  - 使用带有 .getInstance() 的模板 ref 访问核心实例
  - 使用 @eventName 语法注册事件处理器

插槽命名变更： Vue 3 版本强制执行插槽命名约定。已弃用的插槽名称会在 packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:41-52 处抛出错误。当前插槽名称：

#view（原为 #graph-plug）
#canvas（原为 #canvas-plug）
#canvas-above（原为 #canvas-plug-above）
#node-expand-button（原为 #node-expand-holder）

React

React 集成使用 hooks 模式，结合 useGraphInstance 和函数式组件。

组件结构：

入口组件：RelationGraph，来自 packages/platforms/react/src/relation-graph/RelationGraph.tsx:1-41
视图组件：RelationGraphView，来自 packages/platforms/react/src/relation-graph/src/core4react/RelationGraphView.tsx:1-150
在 packages/platforms/react/src/relation-graph/RelationGraph.tsx:34-36 使用 RGDataProvider 上下文

关键集成点：

JSX:
  <RelationGraph ref={graphRef} options={graphOptions}>
    {/* 通过 RGSlotOnNode 提供自定义节点插槽 */}
    <RGSlotOnNode>
      {(node: RGNodeSlotProps) => (
        <div>{node.text}</div>
      )}
    </RGSlotOnNode>

    {/* 其他插槽: RGSlotOnLine, RGSlotOnView, RGSlotOnCanvas, RGSlotOnCanvasAbove */}
  </RelationGraph>

脚本:
  - 从 '@relation-graph/react' 导入 RelationGraph
  - 使用 useRef<RelationGraphExpose>(null) 创建 ref
  - 通过 ref.current?.getInstance() 访问实例
  - 将 options 作为 props 对象传递

插槽模式： React 使用带类型组件的自定义插槽模式，例如 RGSlotOnNode 和 RGSlotOnLine。每个插槽组件都期望以函数作为 children，并接收带类型的 props。插槽检测逻辑位于 packages/platforms/react/src/relation-graph/src/core4react/RelationGraphView.tsx:49-80。

Svelte

Svelte 集成使用 store 进行响应式状态管理。

组件结构：

入口组件：RelationGraph.svelte（在提供的文件中被引用，但未展示）
UI 组件：RelationLinkerUI.svelte，来自 packages/platforms/svelte/src/core4svelte/RelationLinkerUI.svelte:1-67
使用 useGraphInstance 和 useGraphStore 组合式函数

关键集成点：

Svelte 模板:
  <RelationGraph {options} on:onNodeClick={handleNodeClick}>
    <!-- 使用 let: 指令的自定义插槽 -->
    <svelte:fragment slot="node" let:node let:nodeConfig>
      <!-- 自定义节点渲染 -->
    </svelte:fragment>
  </RelationGraph>

脚本:
  - 从 '@relation-graph/svelte' 导入 RelationGraph
  - 定义 options 对象
  - 通过 useGraphInstance() 组合式函数访问实例
  - 使用 on:eventName 语法注册事件处理器

响应式 Store 模式： Svelte 版本在 packages/platforms/svelte/src/core4svelte/RelationLinkerUI.svelte:14-15 处使用 $optionsStore 语法进行响应式订阅。这与 Svelte 内置的 store 系统集成。

Web Components

Web Components 通过自定义元素提供与框架无关的使用方式。

组件结构：

注册为自定义元素（实现细节未在提供的文件中展示）
包名：@relation-graph/web-components，来自 platforms/web-components/package.json:1-65

关键集成点：

HTML:
  <relation-graph id="graph1">
    <!-- 配置通过属性或特性传递 -->
  </relation-graph>

JavaScript:
  - 导入并注册自定义元素
  - 通过 DOM 访问: document.getElementById('graph1')
  - 通过 JavaScript 属性设置 options
  - 通过 addEventListener 监听事件

组件集成流程

下图展示了用户应用代码如何与 RelationGraph 组件包装器及其底层核心实例集成：

graph TD
    UserApp["用户应用代码
Vue/React/Svelte/等"]

    subgraph "组件包装层"
        RGComp["RelationGraph 组件
特定于框架的包装器"]
        RGUI["RelationGraphUI 组件
Canvas 和 UI 编排"]
    end

    subgraph "实例管理"
        Provider["RGProvider / RGDataProvider
上下文/注入系统"]
        GraphStore["graphStore
提供 graphInstance + options"]
    end

    subgraph "核心层"
        RGCore["RelationGraphCore 实例
业务逻辑和状态"]
    end

    UserApp -->|"提供: options, initialData
注册: event handlers"| RGComp
    UserApp -->|"通过以下方式获取实例:
ref.getInstance() / useGraphInstance()"| RGComp

    RGComp -->|"创建/注入"| Provider
    RGComp -->|"渲染"| RGUI

    Provider -->|"管理"| GraphStore
    Provider -->|"创建（如果是新的）"| RGCore

    GraphStore -->|"存储引用"| RGCore

    RGUI -->|"从中读取"| GraphStore
    RGUI -->|"调用其上的方法"| RGCore

    RGComp -->|"setOptions()
setEventEmitHook()"| RGCore

核心概念

RelationGraphCore 实例

RelationGraphCore 类（详见核心架构）是管理图状态、布局、渲染和用户交互的中心对象。每个组件都会创建或接收一个单独的实例。

实例创建：

Vue 2：由 RGProvider 在 packages/platforms/vue2/src/core4vue/RelationGraph.vue:2 创建
Vue 3：由 useRelationGraph 组合式函数在 packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:31-33 创建
React：由 getOrGenerateRGInstance 在 packages/platforms/react/src/relation-graph/RelationGraph.tsx:14 创建

实例访问： 所有平台都会在组件 ref/引用上暴露 getInstance() 方法，但它包含关于数据提供者使用方式的警告。推荐的模式是使用响应式数据集成系统（参见响应式数据集成）。

选项配置

选项通过 options prop 提供，并符合 RGOptions 类型。options 对象用于配置：

布局算法（参见布局系统）
视觉样式（颜色、线宽、节点边框）
交互行为（缩放、拖拽、编辑模式）
性能设置（视口剔除、canvas 渲染）

完整的选项参考请参见配置与选项。

初始数据结构

初始数据可以通过 initialData prop（Vue 2/Vue 3）提供，或在挂载后通过命令式方法提供。数据结构包括：

RGJsonData:
  - nodes: JsonNode[]
      - id: string（必需）
      - text: string
      - x, y: number（可选，若省略则由布局计算）
      - 其他自定义属性

  - lines: JsonLine[]
      - from: string（节点 id）
      - to: string（节点 id）
      - text: string（可选）
      - 其他自定义属性

从 JsonNode/JsonLine 到内部 RGNode/RGLine 类型的数据转换由核心处理（参见数据转换流水线）。

获取实例 - 重要警告

所有平台实现都提供 getInstance() 方法，但包含警告信息：

Vue 2：警告位于 packages/platforms/vue2/src/core4vue/RelationGraph.vue:171
Vue 3：警告位于 packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationGraph.vue:59
React：警告位于 packages/platforms/react/src/relation-graph/RelationGraph.tsx:19

这些警告表明，直接访问实例会绕过响应式数据提供者系统。如果你明确希望直接访问，definitelyNoDataProviderNeeded 选项标志可以抑制这些警告。

数据提供者模式

下图说明了数据提供者模式在不同框架中的工作方式：

graph LR
    subgraph "用户代码"
        UserComponent["应用组件"]
    end

    subgraph "RelationGraph 组件"
        RGWrapper["RelationGraph 包装器
(Vue2/Vue3/React/Svelte)"]
    end

    subgraph "数据提供者层"
        ProviderVue2["Vue2Provider
使用 Vue.set() 实现响应式"]
        ProviderVue3["Vue3Provider
ref()/reactive()"]
        ProviderReact["ReactProvider
useState hooks"]
        ProviderSvelte["SvelteProvider
writable stores"]
    end

    subgraph "核心实例"
        RGCore["RelationGraphCore"]
        GraphData["RGGraphData
nodes: RGNode[]
lines: RGLine[]"]
    end

    UserComponent -->|"传递 options，
注册事件"| RGWrapper

    RGWrapper -->|"setReactiveData4Vue2()
setReactiveData4Vue3()
setReactiveData4React()
setReactiveData4Svelte()"| ProviderVue2
    RGWrapper --> ProviderVue3
    RGWrapper --> ProviderReact
    RGWrapper --> ProviderSvelte

    ProviderVue2 -->|"使其具有响应式"| GraphData
    ProviderVue3 -->|"使其具有响应式"| GraphData
    ProviderReact -->|"使其具有响应式"| GraphData
    ProviderSvelte -->|"使其具有响应式"| GraphData

    RGCore -->|"包含"| GraphData
    RGCore -->|"通过以下方式更新
addNode(), updateNode(),
_dataUpdated()"| GraphData

    GraphData -.->|"响应式更新
触发重新渲染"| RGWrapper

工作原理：

用户组件将 options 和 initialData 传递给 RelationGraph 组件
RelationGraph 创建或接收 RelationGraphCore 实例
特定于平台的数据提供者包装核心的 graphData 对象
当核心通过 addNode()、updateNode() 等更新数据时，数据提供者会检测到变更
特定于框架的响应式系统会触发组件重新渲染
UI 组件从响应式 stores/refs/state 中读取最新数据

有关详细实现，请参见数据管理系统和响应式数据集成。

RelationLinker 组件

除了完整的 RelationGraph 组件外，每个平台还提供一个 RelationLinker 组件，它只渲染线条（不渲染节点）。这对于连接 DOM 中通过其他方式定位的元素很有用。

组件文件：

Vue 2： packages/platforms/vue2/src/core4vue/RelationLinker.vue:1-128
Vue 3： packages/platforms/vue3/src/relation-graph/src/core4vue3/RelationLinker.vue:1-35
React：在 packages/platforms/react/src/relation-graph/src/core4react/RelationLinkerView.tsx:1-110 中被引用
Svelte： packages/platforms/svelte/src/core4svelte/RelationLinkerUI.svelte:1-67

使用模式：

RelationLinker 接受:
  - options: RGOptions
  - lines: JsonLine[]（必需 prop）

渲染:
  - 连接指定坐标点的 SVG 路径
  - 不应用布局算法
  - 不渲染节点

后续步骤

完成基础集成后：

查阅配置与选项以了解可用设置
探索布局系统以了解不同的布局算法
学习用户交互与事件以了解事件处理
研究渲染系统以了解自定义渲染和插槽
参考 API 参考以了解可用的实例方法

若要理解为这些组件提供支持的内部架构，请参见核心架构。