连线数据模型（JsonLine / RGLine）
连线用于描述两个端点之间的关系。普通连线的两个端点必须是节点 id；如果端点不是节点，应使用 虚拟连线 FakeLine。
实际开发中会遇到两种连线对象：
JsonLine：你传入图谱的连线数据。RGLine：图谱运行时生成的连线对象。
1. 最小可用连线
普通连线最少需要 from 和 to：
const line = {
from: 'node-a',
to: 'node-b'
};
推荐显式提供 id 和 text：
const line = {
id: 'line-a-b',
from: 'node-a',
to: 'node-b',
text: '调用'
};
字段规则：
from是起点节点 id。to是终点节点 id。id在源码类型中是必填，但新增普通连线时如果未提供，运行时会生成类似L-xxxxxx的 id。为了后续更新、删除和持久化稳定，业务代码应主动设置id。- 当前源码兼容历史字段：如果没有
from但有source，会把source当作from；如果没有to但有target，会把target当作to；如果没有text但有label，会把label当作text。新代码应使用from/to/text。
2. JsonLine 字段说明
标识、关系与业务字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id |
string |
新增时可自动生成，但强烈建议显式设置 | 连线唯一标识。查询、更新、删除、RGLink 关联都依赖它。 |
from |
string |
必填 | 起点节点 id。普通连线必须能找到对应节点。 |
to |
string |
必填 | 终点节点 id。普通连线必须能找到对应节点。 |
text |
string |
'' |
连线文本。默认连线组件会渲染它；自定义连线插槽也通常读取它。 |
type |
string |
'' |
业务类型。可用于插槽模板分发或 CSS 分类。 |
data |
Record<string, any> |
{} |
业务扩展数据。推荐把权重、状态、描述等业务属性放在这里。 |
selected |
boolean |
false |
多选/编辑状态字段。和 checkedLineId 管理的单个 checked 状态不同。 |
连线路径字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
lineShape |
RGLineShape |
options.defaultLineShape，默认 RGLineShape.StandardStraight |
连线路径形状。影响 SVG path 生成方式。 |
lineDirection |
`‘h’ | ‘v’ | string` |
fromJunctionPoint |
RGJunctionPoint |
options.defaultJunctionPoint，默认 border |
起点与节点相交的位置计算方式。 |
toJunctionPoint |
RGJunctionPoint |
options.defaultJunctionPoint，默认 border |
终点与节点相交的位置计算方式。 |
junctionOffset |
number |
options.defaultLineJunctionOffset，默认 3 |
节点边界外扩距离。可让线条起止点离节点边缘更远或更近。 |
fromJunctionPointOffsetX |
number |
0 |
起点交点 X 方向额外偏移。 |
fromJunctionPointOffsetY |
number |
0 |
起点交点 Y 方向额外偏移。 |
toJunctionPointOffsetX |
number |
0 |
终点交点 X 方向额外偏移。 |
toJunctionPointOffsetY |
number |
0 |
终点交点 Y 方向额外偏移。 |
lineRadius |
number |
options.defaultPolyLineRadius，默认 5 |
折线圆角半径，主要影响正交/折线路径。 |
polyLineStartDistance |
number |
未设置 | 简易折线起始段距离，主要用于 SimpleOrthogonal 类路径。 |
RGLineShape 可选值：
| 枚举 | 数值 | 说明 |
|---|---|---|
RGLineShape.StandardStraight |
1 |
标准直线。路径最简单，适合密度高、关系简单的图。 |
RGLineShape.Curve2 |
2 |
曲线变体。使用通用曲线生成器，视觉上比直线更柔和。 |
RGLineShape.Curve3 |
3 |
曲线变体。适合需要与其他曲线区分的场景。 |
RGLineShape.Curve5 |
5 |
曲线变体。 |
RGLineShape.StandardCurve |
6 |
标准曲线。也是自环或同点连线在部分情况下的回退形状。 |
RGLineShape.Curve7 |
7 |
曲线变体。 |
RGLineShape.Curve8 |
8 |
特殊曲线生成器。 |
RGLineShape.SimpleOrthogonal |
4 |
简易正交折线。常用于树图、流程图。 |
RGLineShape.StandardOrthogonal |
44 |
标准正交线，支持更完整的正交路径和编辑控制点。 |
RGLineShape.HardOrthogonal |
49 |
强制/固定控制点正交线，常由路径编辑操作生成或使用。 |
RGJunctionPoint 可选值：
| 枚举 | 值 | 说明 |
|---|---|---|
RGJunctionPoint.border |
'border' |
自动计算节点边界交点。默认值，适合多数场景。 |
RGJunctionPoint.ltrb |
'ltrb' |
从左、上、右、下边界中选择矩形交点。 |
RGJunctionPoint.tb |
'tb' |
只在上/下边界中选择交点，适合纵向树图。 |
RGJunctionPoint.lr |
'lr' |
只在左/右边界中选择交点，适合横向树图。 |
RGJunctionPoint.left |
'left' |
固定连接到左边。 |
RGJunctionPoint.right |
'right' |
固定连接到右边。 |
RGJunctionPoint.top |
'top' |
固定连接到上边。 |
RGJunctionPoint.bottom |
'bottom' |
固定连接到下边。 |
源码中还存在内部使用的 'horizontalLine'、'verticalLine' 分支，用于特殊线/点场景，不建议作为公开业务配置依赖。
颜色、宽度与文本样式字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
color |
string |
options.defaultLineColor，默认 #cccccc |
连线颜色。会影响 SVG stroke 和默认箭头颜色。 |
lineWidth |
number |
options.defaultLineWidth，默认 2 |
连线宽度。 |
opacity |
number |
1 |
连线透明度，建议取值 0 到 1。 |
className |
string |
undefined |
附加到连线 DOM 的类名。适合主题样式或状态样式扩展。 |
fontColor |
string |
CSS 默认或继承线条颜色 | 连线文本颜色。 |
fontSize |
number |
CSS 默认，通常 12px |
连线文本字号。 |
textOffsetX |
number |
options.defaultLineTextOffsetX 或 0 |
连线文本 X 偏移。 |
textOffsetY |
number |
options.defaultLineTextOffsetY 或 0 |
连线文本 Y 偏移。使用 textPath 时源码会额外做 -6 的纵向修正。 |
placeText |
`‘start’ | ‘center’ | ‘end’ |
textAnchor |
string |
普通文本默认按 'center' 处理；textPath 默认 'middle' |
文本锚点。常用值：'start'、'middle'、'end'。 |
useTextOnPath |
boolean |
options.defaultLineTextOnPath，默认 false |
是否使用 SVG textPath 让文字沿线排列。直线场景下会按普通文字旋转处理；非直线路径更适合开启。 |
文本截断规则：
options.lineTextMaxLength默认66。- 超过长度后会截断并追加
...。 - 如果需要完整文本，建议在自定义连线插槽中自行渲染 tooltip 或多行文本。
箭头与内置效果字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
showStartArrow |
boolean |
false |
是否显示起点箭头。 |
showEndArrow |
boolean |
true |
是否显示终点箭头。 |
startMarkerId |
string |
'' |
自定义起点 SVG marker id。设置后优先使用对应 marker。 |
endMarkerId |
string |
'' |
自定义终点 SVG marker id。设置后优先使用对应 marker。 |
dashType |
number |
0 |
虚线预设类型。会生成类似 rg-line-dashtype-{dashType} 的类名，具体视觉由内置 CSS 或你的 CSS 决定。 |
animation |
number |
0 |
动画预设类型。会生成类似 rg-line-anm-{animation} 的类名，具体动画由 CSS 决定。 |
cssVars |
Record<string, any> |
未设置 | 连线级 CSS 变量扩展。适合高级样式控制。 |
箭头规则：
- 默认终点箭头显示，起点箭头不显示。
- 如果没有提供自定义
markerId，会使用图谱实例内置的默认箭头。 line.isReverse为运行时内部字段，存在时箭头方向会在渲染时交换；不要在持久化数据里主动依赖它。
行为和布局影响字段
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
disablePointEvent |
boolean |
未设置时跟随 options.disableLinePointEvent；导入时常为 false |
禁用该线条的事件命中。 |
hidden |
boolean |
false |
隐藏连线。也会影响 RGLink.rgCalcedVisibility。 |
forDisplayOnly |
boolean |
from === to 时自动为真，否则默认 false |
只用于展示，不参与部分关系分析/力学布局关系。自环线会自动设为展示线。 |
force_elastic |
number |
未设置 | 力导向布局中的连线弹性参数。具体效果取决于当前布局实现。 |
历史兼容：
isShow已废弃。若hidden未设置，源码会把hidden = !isShow。isHide已废弃。若hidden未设置，源码会把hidden = isHide。- 新代码应只使用
hidden。
3. RGLine 运行时字段
RGLine 继承 JsonLine，并补充运行时字段：
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string |
运行时一定存在。未提供时新增 API 会生成。 |
isReverse |
boolean |
内部计算字段，表示渲染方向是否被反转。主要影响箭头、交点和端点偏移的渲染处理。不要手动持久化。 |
普通连线不会直接包含两端节点对象。需要端点节点和多线索引时，应读取对应的 RGLink：
const line = graphInstance.getLineById('line-a-b');
const link = graphInstance.getLinkByLineId('line-a-b');
console.log(link?.fromNode, link?.toNode);
4. 连线创建、查询、更新、删除
创建连线
graphInstance.addLines([
{
id: 'line-a-b',
from: 'a',
to: 'b',
text: '依赖'
}
]);
graphInstance.addLines([
{
id: 'line-b-c',
from: 'b',
to: 'c',
lineShape: RGLineShape.StandardOrthogonal
}
]);
新增普通连线时：
from/to必须能找到现有节点。- 如果
id重复，会跳过新增并输出警告。 - 如果
isFakeLine: true，addLines会把它分流到addFakeLines。
查询连线
const line = graphInstance.getLineById('line-a-b');
const lines = graphInstance.getLines();
const checkedLine = graphInstance.getCheckedLine();
const link = graphInstance.getLinkByLineId('line-a-b');
更新连线
graphInstance.updateLine('line-a-b', {
text: '已更新关系',
color: '#2563eb',
lineWidth: 3,
dashType: 2
});
graphInstance.updateLineData('line-a-b', {
weight: 0.8,
status: 'active'
});
更新规则：
updateLine(id, partial)是浅合并字段。- 更新业务字段优先使用
updateLineData。 - 改变
from/to属于关系结构变化，建议删除旧线再新增新线，避免已有RGLink上下文短暂不一致。
删除连线
graphInstance.removeLineById('line-a-b');
graphInstance.removeLineByIds(['line-b-c', 'line-c-d']);
const line = graphInstance.getLineById('line-x-y');
if (line) {
graphInstance.removeLine(line);
}
5. 多条连线与 multiLineDistance
同一对节点之间可以存在多条连线：
graphInstance.addLines([
{ id: 'ab-1', from: 'a', to: 'b', text: '主链路' },
{ id: 'ab-2', from: 'a', to: 'b', text: '备用链路' },
{ id: 'ab-3', from: 'a', to: 'b', text: '监控链路' }
]);
运行时会通过 RGLink 提供：
totalLinesBetweenNodes：同一节点对之间的总线数。currentLineIndex：当前线在这些线中的索引。
路径生成时会参考 options.multiLineDistance（默认 30）拉开多条线，避免完全重叠。
6. 推荐写法
const line = {
id: 'api-to-db',
from: 'api',
to: 'database',
text: 'SQL 查询',
type: 'request',
lineShape: RGLineShape.StandardOrthogonal,
fromJunctionPoint: RGJunctionPoint.right,
toJunctionPoint: RGJunctionPoint.left,
color: '#2563eb',
lineWidth: 2,
showEndArrow: true,
placeText: 'center',
data: {
protocol: 'postgres',
p95: 38
}
};
推荐原则：
- 结构关系使用
from/to。 - 展示文本使用
text。 - 业务属性放在
data。 - 核心视觉语义放在
color/lineWidth/lineShape，不要只写在 CSS 里。 - 复杂线条模板可结合
type和#line插槽分发。
7. 常见问题
为什么线没有显示？
常见原因：
from/to对应节点不存在。- 线设置了
hidden: true。 - 起点或终点节点隐藏，导致
RGLink.rgCalcedVisibility为假。 - 自定义 FakeLine 目标无法解析几何信息。
- 在性能模式或 EasyView 状态下，主 SVG 层可能被替换为简化绘制。
为什么设置了 lineShape 但路径看起来不明显？
如果两个节点距离很近、节点尺寸较大、或连接点强制固定，某些曲线/折线差异会不明显。可以同时调整：
fromJunctionPoint/toJunctionPointjunctionOffsetlineRadiusmultiLineDistancetextOffsetX/textOffsetY
为什么自定义 CSS 后缩略图没有同步？
缩略图主要读取连线数据字段，例如 color、lineWidth。如果只在 CSS 中改 .rg-line 的 stroke，缩略图无法知道这些变化。