虚拟连线与连接目标（RGFakeLine / RGConnectTarget）

RGFakeLine 用于“连线端点不完全是普通节点”的场景。它复用连线的路径、样式、文本、箭头能力，但端点可以来自节点、节点内部连接点、画布连接点、HTML 元素或你自定义的业务对象。

普通连线和虚拟连线的核心区别：

对比项	普通连线 RGLine	虚拟连线 RGFakeLine
端点来源	from/to 必须是节点 id	from/to 可以是节点 id，也可以是连接目标 id 或自定义对象 id
是否生成普通 RGLink	是	通常不是普通 RGLink；部分节点/连接点之间的 FakeLine 可被内部转换为类似 link 的分析上下文
是否参与布局关系	会影响关系网络和部分布局	默认不作为普通结构关系参与节点布局
典型用途	节点与节点之间的业务关系	编辑器锚点、面板连接线、节点内部端口、画布标注、HTML 元素辅助线

1. 最小 FakeLine

graphInstance.addFakeLines([
  {
    id: 'fake-1',
    isFakeLine: true,
    from: 'node-a',
    fromType: RGInnerConnectTargetType.Node,
    to: 'port-1',
    toType: RGInnerConnectTargetType.NodePoint,
    text: '连接到端口'
  }
]);

必备字段：

• id：虚拟连线唯一 id，建议显式设置。
• from：起点目标 id。
• to：终点目标 id。
• fromType：起点目标类型。
• toType：终点目标类型。

addFakeLines() 会把传入对象转换为运行时 RGFakeLine。如果使用 addLines() 并设置 isFakeLine: true，源码会把这条线分流到 FakeLine 数据集合。

2. RGFakeLine 字段说明

RGFakeLine 继承 JsonLine 的绝大多数字段，因此以下字段同样可用：

• 文本：text、fontColor、fontSize、textOffsetX、textOffsetY、placeText、textAnchor、useTextOnPath
• 路径：lineShape、lineDirection、fromJunctionPoint、toJunctionPoint、junctionOffset、lineRadius
• 样式：color、lineWidth、opacity、className、dashType、animation、cssVars
• 箭头：showStartArrow、showEndArrow、startMarkerId、endMarkerId
• 行为：disablePointEvent、hidden、forDisplayOnly、data

FakeLine 特有或特别重要的字段：

字段	类型	默认值	说明
isFakeLine	boolean	通过 addFakeLines 添加时会被设为 true	标识它是虚拟连线。通过 addLines 添加 FakeLine 时必须设置。
fromType	`RGInnerConnectTargetType	string`	普通线默认 Node；FakeLine 未指定时常按 CanvasPoint 处理
toType	`RGInnerConnectTargetType	string`	普通线默认 Node；FakeLine 未指定时常按 CanvasPoint 处理
from	string	必填	起点目标 id。含义由 fromType 决定。
to	string	必填	终点目标 id。含义由 toType 决定。
forDisplayOnly	boolean	from === to 时自动为真；HTML element line 旧 API 会设置为真	只展示，不作为结构关系参与部分分析。

3. 端点类型 RGInnerConnectTargetType

枚举	值	说明
RGInnerConnectTargetType.Node	'node'	普通节点。from/to 是节点 id。
RGInnerConnectTargetType.NodePoint	'NodePoint'	节点内部连接点。通常由节点内部的 RGConnectTarget 注册，能关联回所属节点。
RGInnerConnectTargetType.CanvasPoint	'CanvasPoint'	画布连接点。通常由画布层的 RGConnectTarget 注册，坐标跟随画布。
RGInnerConnectTargetType.HTMLElementId	'HTMLElementId'	通过页面 HTML 元素 id 解析目标。适合连接图谱外或图谱层中的 DOM 元素。
RGInnerConnectTargetType.ViewPoint	'ViewPoint'	视图层点位类型。类型定义中存在，具体场景通常由内部或扩展组件使用。

自定义类型：

• fromType/toType 可以使用任意字符串。
• 自定义类型必须通过 graphInstance.setFakeLineTargetRender() 提供几何信息。

4. RGConnectTarget 的作用

RGConnectTarget 用于把任意 DOM 区域注册为“可连接目标”。FakeLine 或编辑器拖线逻辑可以通过 targetId 找到它，并读取它的位置、尺寸和连接点信息。

React 示例：

<RGConnectTarget
  targetId="user-card-port-out"
  targetType={RGInnerConnectTargetType.NodePoint}
  junctionPoint={RGJunctionPoint.right}
  targetData={{ portName: 'output' }}
>
  <button>输出端口</button>
</RGConnectTarget>

Vue 示例：

<RGConnectTarget
  target-id="user-card-port-in"
  :target-type="RGInnerConnectTargetType.NodePoint"
  :junction-point="RGJunctionPoint.left"
  :target-data="{ portName: 'input' }"
>
  <span class="port"></span>
</RGConnectTarget>

5. RGConnectTarget 属性说明

属性	类型	默认值	说明
targetId	string	必填	连接目标 id。FakeLine 的 from/to 要指向这个值。
targetType	string	位于节点中时通常按 NodePoint，其他场景常按 CanvasPoint	连接目标类型。要与 FakeLine 的 fromType/toType 对应。
junctionPoint	RGJunctionPoint	RGJunctionPoint.border	从该目标出线/入线时采用的连接点规则。
targetData	Record<string, any>	未设置	连接目标扩展数据。拖线回调、目标解析时可读取。
lineTemplate	Partial<JsonLine>	未设置	从该目标发起拖线时使用的连线模板。可预设颜色、线型、业务数据。
disableDrop	boolean	false	是否禁止把线端点拖放到该目标。
disableDrag	boolean	false	是否禁止从该目标发起拖线。
onLineVertexBeDropped	RGLineVertexBeDroppedEventHandler	未设置	线端点拖放到该目标时触发。
onDragConnectStart	(template, event) => void	未设置	从该目标开始拖线时触发。
onDragConnectEnd	RGLineConnectEventHandler	未设置	从该目标拖线结束时触发。
className	string	未设置	自定义类名。
style	`Record<string, string	number>`	未设置
domMode	`‘wrap’	‘contents’`	平台实现默认值
measureSelector	string	未设置	指定用于测量尺寸/位置的内部元素选择器。
strictMeasureTarget	boolean	未设置	严格使用测量目标。复杂 DOM 结构时可避免测量到错误元素。
forSvg	boolean	未设置	SVG 场景辅助属性，具体取决于平台组件实现。

6. 用 NodePoint 连接节点内部端口

适合系统架构图、流程图、编辑器端口等场景。

const fakeLine = {
  id: 'api-output-to-db-input',
  isFakeLine: true,
  from: 'api-output',
  fromType: RGInnerConnectTargetType.NodePoint,
  to: 'db-input',
  toType: RGInnerConnectTargetType.NodePoint,
  lineShape: RGLineShape.StandardOrthogonal,
  text: 'SQL'
};

关键点：

• api-output 和 db-input 必须由 RGConnectTarget 注册。
• 如果连接点在节点内部，注册信息会记录所属节点；部分关系分析 API 可以通过 FakeLine 解析回节点。
• 如果节点插槽重新渲染导致 DOM 结构变化，确保 targetId 保持稳定。

7. 用 CanvasPoint 连接画布坐标对象

适合泳道、分组区域、坐标标注、自由画布图元。

<template #canvas>
  <RGConnectTarget
    target-id="lane-a-anchor"
    :target-type="RGInnerConnectTargetType.CanvasPoint"
    :junction-point="RGJunctionPoint.right"
  >
    <div style="position:absolute;left:120px;top:80px;width:16px;height:16px;" />
  </RGConnectTarget>
</template>

对应 FakeLine：

graphInstance.addFakeLines([
  {
    id: 'node-to-lane',
    isFakeLine: true,
    from: 'service-a',
    fromType: RGInnerConnectTargetType.Node,
    to: 'lane-a-anchor',
    toType: RGInnerConnectTargetType.CanvasPoint,
    text: '属于'
  }
]);

canvas 插槽内的目标会随画布平移和缩放，因此 FakeLine 能保持画布坐标一致。

8. 用 HTMLElementId 连接 HTML 元素

HTMLElementId 会通过 document.getElementById(targetId) 测量元素位置，并转换为画布坐标。

graphInstance.addFakeLines([
  {
    id: 'html-a-to-html-b',
    isFakeLine: true,
    from: 'html-panel-a',
    fromType: RGInnerConnectTargetType.HTMLElementId,
    to: 'html-panel-b',
    toType: RGInnerConnectTargetType.HTMLElementId,
    forDisplayOnly: true,
    text: '外部辅助线'
  }
]);

graphInstance.updateElementLines();

注意：

• 元素必须有真实 DOM id。
• 当元素位置或尺寸变化时，通常需要调用 updateElementLines()，图谱内部也会在部分时机自动更新。
• 如果找不到元素，内部目标会标记为 hidden，线不会正确显示。
• 旧 API addElementLines、getElementLines、clearElementLines 仍有兼容，但文档推荐使用 addFakeLines。

9. 自定义目标类型：setFakeLineTargetRender

当端点不是节点、连接点或 HTML 元素时，可以注册目标解析器：

graphInstance.setFakeLineTargetRender((targetType, targetId, fakeLine) => {
  if (targetType === 'group-area') {
    const group = groupMap.get(targetId);
    if (!group) return null;

    return {
      id: targetId,
      text: group.name,
      targetType,
      x: group.x,
      y: group.y,
      nodeShape: RGNodeShape.rect,
      el_W: group.width,
      el_H: group.height,
      junctionPoint: RGJunctionPoint.border,
      targetData: group
    };
  }

  return null;
});

返回对象至少需要：

字段	说明
x / y	目标左上角画布坐标。
el_W / el_H	目标宽高。
nodeShape	目标形状，影响连接点计算。
targetType	目标类型，建议返回传入的 targetType。

可选字段：

• id / text：方便调试或插槽显示。
• junctionPoint：目标自己的连接点规则。
• targetData：业务数据。
• hidden：设置为 true 时可让该目标不参与渲染。

10. FakeLine 查询与更新

const fakeLine = graphInstance.getFakeLineById('fake-1');
const fakeLines = graphInstance.getFakeLines();

graphInstance.updateFakeLine('fake-1', {
  text: '更新后的虚拟线',
  color: '#f97316',
  lineShape: RGLineShape.StandardOrthogonal
});

graphInstance.removeFakeLineById('fake-1');
graphInstance.clearFakeLines();

兼容说明：

• updateLine('fake-1', ...) 主要更新普通线集合；更新 FakeLine 推荐使用 updateFakeLine。
• getCheckedLine() 会先查普通线，找不到时再查 FakeLine，因此 checked 状态可以覆盖两类线。

11. 常见问题

FakeLine 为什么没有显示？

常见原因：

• fromType/toType 与实际目标类型不一致。
• targetId 没有被 RGConnectTarget 注册。
• 自定义 setFakeLineTargetRender 没有返回目标几何信息。
• HTML 元素 id 找不到，或元素尚未挂载。
• 目标尺寸为 0，导致路径计算异常。
• hidden: true 或目标自身隐藏。

FakeLine 会影响自动布局吗？

通常不会像普通 RGLine 那样参与主关系布局。它更适合表达编辑器辅助关系、端口连接或跨层连接。需要影响布局的结构关系应使用普通 lines。

FakeLine 能参与关系分析吗？

部分 FakeLine 如果两端能解析回节点，例如 Node、节点内部 NodePoint、部分 CanvasPoint，内部可以构造类似 link 的上下文供关系查询使用。但不要把所有 FakeLine 都当作完整结构关系；跨 HTML 元素或自定义对象时尤其要谨慎。

12. 下一步阅读

• 连线数据模型
• 关联对象数据
• 自定义连线插槽
• 画布拓展内容
• 事件系统大全