快速开始
本页是 relation-graph 的总览级入门页面。
如果你刚开始接触这个项目，最简单的理解方式是：
- 选择与你当前平台匹配的包。
- 渲染一个具有明确宽高的图容器。
- 加载图数据。
- 在需要时注册交互事件。
- 随着图能力逐步变复杂，再进入布局、样式和实例 API。
如果你想看某个框架下的具体代码，请直接阅读下方对应平台页面。
1. 选择你的平台
relation-graph 支持多种前端接入方式：
| 平台 | 推荐包 / 入口 | 快速开始页面 |
|---|---|---|
| Vue 3 | @relation-graph/vue |
Vue3 快速开始 |
| Vue 2 | @relation-graph/vue2 |
Vue2 快速开始 |
| React | @relation-graph/react |
React 快速开始 |
| Svelte | @relation-graph/svelte |
Svelte 快速开始 |
| HTML / Web Components | relation-graph-webcomponents |
HTML / Web Components 快速开始 |
如果你已经确定要用哪个框架，可以直接进入对应页面。
如果你还没有开始写具体代码，建议先读完本页，了解几个平台共通的使用模型。
2. 共通的接入模型
无论你使用哪个平台，整体接入流程都非常相似：
- 创建一个具有明确尺寸的容器。
- 在容器内部渲染图组件。
- 准备节点和连线数据。
- 通过以下两种方式之一加载数据：
- 使用
setJsonData(...)一次性初始化整张图； - 使用
addNodes(...)+addLines(...)做增量更新。
- 使用
- 执行布局和视口相关操作，例如居中、缩放至适应屏幕。
- 监听节点点击、连线点击或编辑相关事件。
不同平台之间最大的差异，不在图数据模型本身，而在于你如何获取图实例和响应式状态：
- Vue 3 / React / Svelte 使用
RGProvider+RelationGraph+ hooks 风格访问。 - Vue 2 使用
RGProvider+RelationGraph+graphStoreMixin。 - HTML / Web Components 使用 DOM 事件和
onReady回调来暴露图实例。
3. 推荐的启动路径
对于大多数新项目来说，最简单有效的起步方式如下：
Step 1：先从一个小图开始
建议先用一个很小的数据集：
- 1 个根节点
- 2 到 5 个子节点
- 少量基础连线
这样你可以先验证以下事情：
- 包是否安装成功
- 是否正常渲染
- 事件绑定是否生效
- 布局是否正常
- 视口尺寸是否正确
Step 2：先使用一次性初始化
如果你当前只是希望先把一张图显示出来，setJsonData(...) 往往是最快的入口。
以下场景很适合先用它：
- 你的数据本来就是一个完整 payload
- 你在做只读图展示
- 你只是想快速验证布局效果
Step 3：做编辑器时再切换到增量 API
如果你的图要支持：
- 编辑
- 动态插入 / 删除
- 工作流类操作
- 画布工具或白板行为
那么更建议切换到细粒度 API，例如：
addNodes(...)addLines(...)- 更新 / 删除类 API
- 通过实例方法做运行时选项更新
这通常会比反复整图重建更稳定。
4. 容器尺寸很重要
一个常见问题是：图视口的表现完全依赖它的父容器尺寸。
在排查布局或缩放问题之前，先确认图组件的父容器确实有真实尺寸，例如：
- 全屏页面高度
- 固定像素高度
- 仪表盘中的自适应面板高度
如果父容器尺寸不稳定，或者实际塌缩为 0，图的行为通常就不会符合预期。
5. 常见的数据加载模式
relation-graph 一般可以归纳为三种常见模式：
模式 A：一次性展示
使用 setJsonData(...)。
适合：
- 文档示例
- 详情页
- 只读图展示
- 首次集成验证
模式 B：增量式构图
使用 addNodes(...)、addLines(...) 及相关 API。
适合：
- 编辑器
- 白板
- 工作流设计器
- 高频更新的图应用
模式 C：初始渲染数据
在对应框架包支持的情况下使用 initialData。
适合：
- 页面初始渲染
- SSR 友好场景
- 已知图数据下的首屏展示
6. 事件与运行时控制
当图已经能显示出来之后，下一步通常就是交互：
- 节点点击
- 连线点击
- 视口移动
- 编辑状态
- 选中状态
所有平台包都提供了处理这些事件的方式，只是具体写法会因框架而不同。
在运行时，你通常会围绕一个图实例做以下事情：
- 更新选项
- 加载或替换数据
- 将图移动到中心
- 缩放到适合视口
- 创建或切换布局
具体到每个平台如何拿到实例，请看对应平台的快速开始页面。
7. 接下来应该看哪一页？
根据你当前的目标进入对应页面：
- 我想看具体框架的接入方式：
- 我想先理解图模型：
- 我想控制布局和样式：
- 我想处理交互：
- 我想做更底层的运行时控制：
8. 推荐的第一个里程碑
如果你想尽快完成一个有实际意义的第一步，建议先做到以下目标：
- 把一张图成功渲染到页面上
- 加载一个小数据集
- 点击一个节点并打印它的 id
- 将图居中并缩放适配
- 确认布局在你的框架里运行正常
完成这些之后，再继续进入：
- 自定义节点内容
- 编辑能力
- 更高级的布局规则
- 更大规模的图数据
这通常是从“能安装”走到“能在业务里工作”的最快路径。