Relation Graph

图谱全局配置项（`RGOptions`）

RGOptions 定义 relation-graph 的全局行为：交互方式、默认节点样式、默认连线样式、布局配置、工具栏、性能模式和运行时效果。

它不是节点/连线数据本身，而是图谱实例的“默认规则”和“运行参数”。

1. 配置的生效方式

初始化配置

const graphOptions = {
  instanceId: 'main-graph',
  showToolBar: false,
  wheelEventAction: 'scroll',
  dragEventAction: 'move',
  defaultNodeColor: '#ffffff',
  defaultLineColor: '#cbd5e1',
  layout: {
    layoutName: 'center'
  }
};

传给组件：

<RelationGraph options={graphOptions} />

运行时更新配置

图谱初始化后，不要只替换外部响应式 options 对象来期望所有行为自动同步。运行时修改配置应使用实例 API：

graphInstance.updateOptions({
  wheelEventAction: 'zoom',
  dragEventAction: 'selection'
});

也可以使用：

graphInstance.setOptions({
  showToolBar: true
});

当前源码中 setOptions 与 updateOptions 都会走 _updateOptions() 并触发视图更新。传入 layout 时，会与当前 options.layout 合并，并同步给当前布局器。

2. 默认值总览

源码 createDefaultConfig() 中的主要默认值如下：

配置项	默认值	说明
`instanceId`	`''`	图谱实例 id。未设置时框架层通常会生成实例 id。SSR 或多图同页时建议显式设置。
`debug`	`true`	是否开启调试输出。源码会同步到 `window.relationGraphDebug`。
`showToolBar`	`true`	是否显示内置小工具栏。
`backgroundColor`	`'transparent'`	图谱背景色，会写入 CSS 变量 `--rg-background-color`。
`checkedItemBackgroundColor`	`undefined`	checked 高亮背景色。未设置时使用 CSS 默认 `rgba(150, 150, 150, 0.2)`。
`disableWheelEvent`	`false`	是否禁用普通鼠标滚轮响应。
`wheelEventAction`	`'zoom'`	普通滚轮行为。可选 `'zoom'`、`'scroll'`、`'none'`。
`dragEventAction`	`'move'`	画布拖拽行为。可选 `'move'`、`'selection'`、`'none'`。
`fullscreenElementXPath`	`''`	全屏时使用的 DOM 查询选择器。未设置时使用图谱根 DOM。
`disableDragNode`	`false`	是否全局禁止节点拖拽。
`disableDragLine`	`true`	是否禁止拖拽普通线移动两端节点。
`canvasMoveMode`	`false`	内部画布移动模式状态，通常由交互过程自动维护。
`disableNodePointEvent`	`false`	是否全局禁用节点事件。
`disableLinePointEvent`	`false`	是否全局禁用连线事件。
`enableNodeXYAnimation`	`false`	是否启用节点位置变化动画。通常由布局流程短暂开启。
`enableCanvasTransformAnimation`	`false`	是否启用画布平移/缩放动画。
`reLayoutWhenExpandedOrCollapsed`	`false`	展开/折叠节点后是否自动重新布局。
`defaultExpandHolderPosition`	`'hide'`	默认展开/折叠按钮位置。
`toolBarDirection`	`'h'`	内置工具栏方向。
`toolBarPositionH`	`'left'`	内置工具栏水平位置。
`toolBarPositionV`	`'bottom'`	内置工具栏垂直位置。
`defaultNodeColor`	`'#ffffff'`	默认节点背景色。
`defaultNodeBorderColor`	`'#666666'`	默认节点边框色。
`defaultNodeBorderWidth`	`1`	默认节点边框宽度。
`defaultNodeBorderRadius`	`4`	默认节点圆角。
`defaultNodeShape`	`RGNodeShape.rect`	默认节点形状。
`defaultNodeWidth`	`undefined`	默认节点宽度。未设置时由内容/DOM 测量决定。
`defaultNodeHeight`	`undefined`	默认节点高度。未设置时由内容/DOM 测量决定。
`defaultLineColor`	`'#cccccc'`	默认连线颜色。
`defaultLineWidth`	`2`	默认连线宽度。
`defaultLineShape`	`RGLineShape.StandardStraight`	默认连线形状。
`defaultLineTextOffsetX`	`undefined`	默认连线文本 X 偏移。未设置按 `0` 计算。
`defaultLineTextOffsetY`	`undefined`	默认连线文本 Y 偏移。未设置按 `0` 计算。
`defaultJunctionPoint`	`RGJunctionPoint.border`	默认连线端点连接位置规则。
`defaultLineJunctionOffset`	`3`	默认连线端点边界外扩距离。
`defaultPolyLineRadius`	`5`	默认折线圆角半径。
`placeOtherGroup`	`true`	自动布局时是否摆放主网络之外的其他连通分组和孤立节点。
`defaultLineTextOnPath`	`false`	默认是否使用 SVG `textPath` 绘制线文本。
`lineTextMaxLength`	`66`	连线文本最大显示长度，超过后截断追加 `...`。
`multiLineDistance`	`30`	同一节点对多条连线之间的间距。
`layout`	`{ layoutName: 'center' }`	默认布局配置。
`canvasZoom`	`100`	当前画布缩放百分比。运行时状态，一般不作为初始化配置使用。
`mouseWheelSpeed`	`10`	滚轮缩放/滚动速度系数。
`minCanvasZoom`	`5`	最小缩放百分比。
`maxCanvasZoom`	`500`	最大缩放百分比。
`performanceMode`	`false`	性能模式。低缩放时可能启用 EasyView，减少 DOM 渲染压力。
`viewHeight`	`'100%'`	图谱视图高度。根节点内联样式会使用它。

3. 交互配置

`wheelEventAction`

控制用户不按 Ctrl/Cmd 时的滚轮行为。

值	说明
`'zoom'`	默认值。滚轮缩放画布。
`'scroll'`	滚轮平移画布，类似滚动画布视图。按 Ctrl/Cmd 时仍会走缩放逻辑。
`'none'`	不处理普通滚轮。

`dragEventAction`

控制用户在画布空白区域按下并拖拽时的行为。

值	说明
`'move'`	默认值。拖拽移动画布。
`'selection'`	拖拽创建框选区域。
`'none'`	不移动画布、不创建框选；源码会按点击画布处理。

补充规则：

即使 dragEventAction 是 'move'，按住 Shift 拖拽也会进入框选。
如果当前事件目标是线条、输入框或某些编辑器元素，源码会先处理对应对象逻辑。

拖拽和事件禁用

配置项	默认值	说明
`disableDragNode`	`false`	全局禁止节点拖拽。单个节点也可设置 `node.disableDrag`。
`disableDragLine`	`true`	禁止拖拽线条移动两端节点。设为 `false` 后，拖拽普通线会带动两端节点移动。
`disableNodePointEvent`	`false`	全局禁用节点事件命中。单个节点可用 `node.disablePointEvent` 覆盖。
`disableLinePointEvent`	`false`	全局禁用连线事件命中。单条线可用 `line.disablePointEvent` 覆盖。

生效优先级：

节点事件：node.disablePointEvent 未设置时，使用 options.disableNodePointEvent。
节点拖拽：node.disableDrag || options.disableDragNode 任一为真即不可拖。
连线事件：line.disablePointEvent 未设置时，使用 options.disableLinePointEvent。

4. 节点默认配置

配置项	类型	默认值	影响
`defaultNodeColor`	`string`	`'#ffffff'`	节点未设置 `color` 时的背景色。也会写入根 CSS 变量。
`defaultNodeBorderColor`	`string`	`'#666666'`	节点未设置 `borderColor` 时的边框色。
`defaultNodeBorderWidth`	`number`	`1`	节点未设置 `borderWidth` 时的边框宽度。
`defaultNodeBorderRadius`	`number`	`4`	节点未设置 `borderRadius` 时的圆角。
`defaultNodeShape`	`RGNodeShape`	`RGNodeShape.rect`	节点未设置 `nodeShape` 时的形状。影响默认渲染、连线交点、缩略图。
`defaultNodeWidth`	`number	undefined`	`undefined`
`defaultNodeHeight`	`number	undefined`	`undefined`
`defaultExpandHolderPosition`	`‘hide’	‘left’	‘top’
`checkedItemBackgroundColor`	`string	undefined`	`undefined`

RGNodeShape 可选值：

枚举	数值	说明
`RGNodeShape.circle`	`0`	圆形节点。连线交点按圆/椭圆边界计算。
`RGNodeShape.rect`	`1`	矩形节点。默认值。

示例：

const graphOptions = {
  defaultNodeShape: RGNodeShape.rect,
  defaultNodeColor: '#f8fafc',
  defaultNodeBorderColor: '#64748b',
  defaultNodeBorderWidth: 1,
  defaultNodeBorderRadius: 6,
  defaultNodeWidth: 140,
  defaultNodeHeight: 48,
  defaultExpandHolderPosition: 'right'
};

注意：

默认配置只在节点没有设置对应字段时生效。
节点创建后再修改默认值，不一定会把旧节点字段改写成新值；但根 CSS 变量和有效值转换会反映部分运行时效果。
缩略图/EasyView 更依赖数据字段和有效值，不建议只通过插槽 CSS 表达核心节点颜色。

5. 连线默认配置

配置项	类型	默认值	影响
`defaultLineColor`	`string`	`'#cccccc'`	线未设置 `color` 时的颜色。
`defaultLineWidth`	`number`	`2`	线未设置 `lineWidth` 时的宽度。
`defaultLineShape`	`RGLineShape`	`RGLineShape.StandardStraight`	线未设置 `lineShape` 时的路径形状。
`defaultJunctionPoint`	`RGJunctionPoint`	`RGJunctionPoint.border`	线未设置端点连接规则时使用。
`defaultLineJunctionOffset`	`number`	`3`	线端点相对节点边界的默认外扩距离。
`defaultPolyLineRadius`	`number`	`5`	折线默认圆角半径。
`defaultLineTextOnPath`	`boolean`	`false`	线未设置 `useTextOnPath` 时，是否让文字沿路径渲染。
`defaultLineTextOffsetX`	`number	undefined`	`undefined`
`defaultLineTextOffsetY`	`number	undefined`	`undefined`
`lineTextMaxLength`	`number`	`66`	线文本最大长度，超出后截断。
`multiLineDistance`	`number`	`30`	同一节点对多条连线的间距。
`defaultLineMarker`	`object`	见下文	默认 SVG 箭头 marker。

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'`	固定下侧。

默认箭头：

defaultLineMarker: {
  viewBox: '0 0 12 12',
  markerWidth: 20,
  markerHeight: 20,
  refX: 3,
  refY: 3,
  data: 'M 0 0, V 6, L 4 3, Z'
}

这些字段会用于内置 <marker> 定义。单条线也可以通过 startMarkerId/endMarkerId 引用你自己定义的 marker。

6. 工具栏与视图配置

配置项	默认值	可选值	说明
`showToolBar`	`true`	`boolean`	是否显示内置工具栏。
`toolBarDirection`	`'h'`	`‘h’	‘v’`
`toolBarPositionH`	`'left'`	`‘left’	‘center’
`toolBarPositionV`	`'bottom'`	`‘top’	‘center’
`viewHeight`	`'100%'`	CSS 高度字符串	图谱视图高度。
`backgroundColor`	`'transparent'`	CSS 颜色	图谱背景色。
`fullscreenElementXPath`	`''`	CSS selector 字符串	调用 `fullscreen()` 时优先全屏的目标元素。

示例：

const graphOptions = {
  showToolBar: true,
  toolBarDirection: 'v',
  toolBarPositionH: 'right',
  toolBarPositionV: 'top',
  backgroundColor: '#f8fafc'
};

7. 布局配置 `layout`

layout 是默认布局参数，会在以下场景使用：

setJsonData(data) 后自动 doLayout(data.rootId)。
手动调用 doLayout()。
appendJsonData(data, true) 追加后重新布局。
applyInitialData(data) 的布局阶段。

基础结构：

const graphOptions = {
  layout: {
    layoutName: 'tree'
  }
};

支持的 layoutName：

值	说明
`'center'`	中心布局，默认布局。继承力导向能力，可支持自动布局。
`'force'`	力导向布局。
`'tree'`	树布局。
`'circle'`	环形布局。
`'fixed'`	固定布局，不自动改节点坐标。
`'smart-tree'`	智能树布局。
`'io-tree'`	输入输出树布局。
`'folder'`	文件夹/目录式布局。

通用布局字段：

字段	类型	说明
`layoutName`	`string`	布局名称。
`layoutDirection`	`‘h’	‘v’`
`fixedRootNode`	`boolean`	根节点位置是否作为布局锚点。源码主布局中会设为 `true`。
`rotate`	`number`	布局旋转角度，具体效果取决于布局器。
`alignItemsX`	`‘start’	‘center’
`alignItemsY`	`‘start’	‘center’
`autoLayouting`	`boolean`	运行时只读状态，表示自动布局是否正在运行。
`supportAutoLayout`	`boolean`	运行时状态，表示当前布局是否支持自动布局。

树布局字段：

字段	类型	默认/说明
`from`	`‘left’	‘top’
`treeNodeGapH`	`number`	横向节点间距。
`treeNodeGapV`	`number`	纵向节点间距。
`levelGaps`	`number[]`	各层级之间的距离。数组不足时通常沿用后续计算逻辑。
`layoutExpansionDirection`	`‘start’	‘center’
`simpleTree`	`boolean`	是否按单向简单树展开。
`ignoreNodeSize`	`boolean`	是否忽略节点实际尺寸做布局。
`alignParentItemsX`	`‘start’	‘center’
`alignParentItemsY`	`‘start’	‘center’

力导向/中心布局字段：

字段	类型	说明
`fastStart`	`boolean`	力导向是否从更快的初始状态开始。
`maxLayoutTimes`	`number`	最大迭代次数。
`byNode`	`boolean`	是否启用节点之间的斥力。
`byLine`	`boolean`	是否启用连线弹力。
`force_node_repulsion`	`number`	节点斥力系数。越大通常越分散。
`force_line_elastic`	`number`	连线弹力系数。越大通常越紧凑。
`distanceCoefficient`	`number`	中心布局的理想距离系数。
`disableAsForceLayout`	`boolean`	中心布局是否禁用继承来的力导向能力。
`levelGaps`	`number[]`	中心/层级距离控制。

示例：

const graphOptions = {
  layout: {
    layoutName: 'tree',
    from: 'left',
    treeNodeGapH: 180,
    treeNodeGapV: 40,
    levelGaps: [120, 180, 220],
    layoutExpansionDirection: 'center'
  }
};

8. 多分组与孤立节点

placeOtherGroup 默认 true。

作用：

doLayout() 会先从根节点找到主关系网络。
不属于主网络的其他连通分组会被单独布局。
孤立节点会按简单网格摆放。
最终再把多个分组按网格排列，避免全部堆在一起。

设置为 false：

graphInstance.updateOptions({
  placeOtherGroup: false
});

适合你只想布局根节点所在主网络，其他节点保持原位置的场景。

类型定义中还保留 placeOtherNodes，但当前实际布局实现读取的是 placeOtherGroup。新代码应使用 placeOtherGroup。

9. 性能与动画配置

配置项	默认值	说明
`performanceMode`	`false`	性能模式。低缩放时可能启用简化 EasyView，减少大量 DOM 节点和线条的渲染成本。
`enableNodeXYAnimation`	`false`	节点位置变化动画。实例 API `enableNodeXYAnimation()` / `disableNodeXYAnimation()` 可控制。
`enableCanvasTransformAnimation`	`false`	画布 transform 动画。实例 API `enableCanvasAnimation()` / `disableCanvasAnimation()` 可控制。
`reLayoutWhenExpandedOrCollapsed`	`false`	节点展开/折叠后是否自动调用布局。

性能模式细节：

源码在缩放跨过约 40% 时会切换 showEasyView。
showEasyView 是运行时内部状态，不建议作为初始化配置。
性能模式下 DOM 可能不是完整节点/线集合，依赖 DOM 的自定义统计或截图逻辑要谨慎。

动画建议：

自动布局时短暂开启节点动画可以提升视觉连续性。
高频实时数据刷新时不建议长期打开动画，否则可能影响性能和交互响应。

10. 加载与运行时内部状态

这些字段出现在 RGOptionsFull 中，但更适合作为运行时状态，而不是普通初始化配置：

字段	说明	推荐操作
`graphLoading`	是否显示加载遮罩。	使用 `graphInstance.loading(text)` / `clearLoading()`。
`graphLoadingText`	加载文字。	使用 `loading(text)` 设置。
`checkedNodeId`	当前 checked 节点 id。	使用 `setCheckedNode()` / `clearChecked()`。
`checkedLineId`	当前 checked 连线 id。	使用 `setCheckedLine()` / `clearChecked()`。
`draggingNodeId`	当前拖拽节点 id。	内部维护。
`creatingSelection`	是否正在框选。	内部维护。
`selectionView`	框选矩形。	通过事件或 hooks 读取。
`creatingNodePlot`	是否正在创建节点。	由创建节点交互维护。
`newNodeTemplate`	当前新节点模板。	由创建节点交互维护。
`creatingLinePlot`	是否正在创建线。	由创建线交互维护。
`newLineTemplate`	当前新线模板。	由创建线交互维护。
`newLinkTemplate`	当前新 link 模板。	内部维护。
`editingController`	节点编辑控制器状态。	通过编辑 API 或 hooks 使用。
`editingLineController`	连线编辑控制器状态。	通过编辑 API 或 hooks 使用。
`nodeConnectController`	节点连接控制器状态。	内部/编辑器组件维护。
`showMiniView`	缩略图是否挂载。	由 `RGMiniView` 挂载状态维护。
`showReferenceLine`	对齐参考线是否启用。	由参考线组件挂载状态维护。
`snapshotting`	是否正在截图/导出。	内部维护。

11. 推荐配置模板

只读展示图

const graphOptions = {
  instanceId: 'readonly-graph',
  showToolBar: true,
  wheelEventAction: 'zoom',
  dragEventAction: 'move',
  defaultNodeColor: '#ffffff',
  defaultNodeBorderColor: '#cbd5e1',
  defaultNodeBorderWidth: 1,
  defaultNodeBorderRadius: 6,
  defaultLineColor: '#94a3b8',
  defaultLineWidth: 2,
  defaultLineShape: RGLineShape.StandardCurve,
  minCanvasZoom: 20,
  maxCanvasZoom: 300,
  layout: {
    layoutName: 'center'
  }
};

图谱编辑器

const graphOptions = {
  instanceId: 'editor-graph',
  showToolBar: false,
  wheelEventAction: 'scroll',
  dragEventAction: 'selection',
  disableDragNode: false,
  disableDragLine: true,
  disableLinePointEvent: false,
  defaultExpandHolderPosition: 'right',
  defaultNodeWidth: 140,
  defaultNodeHeight: 48,
  defaultLineShape: RGLineShape.StandardOrthogonal,
  defaultJunctionPoint: RGJunctionPoint.border,
  multiLineDistance: 36,
  reLayoutWhenExpandedOrCollapsed: false,
  layout: {
    layoutName: 'fixed'
  }
};

树形图

const graphOptions = {
  instanceId: 'tree-graph',
  wheelEventAction: 'zoom',
  dragEventAction: 'move',
  defaultLineShape: RGLineShape.StandardOrthogonal,
  defaultJunctionPoint: RGJunctionPoint.lr,
  layout: {
    layoutName: 'tree',
    from: 'left',
    treeNodeGapH: 180,
    treeNodeGapV: 30,
    layoutExpansionDirection: 'center'
  }
};

12. 常见误区

直接改 `options` 对象为什么不生效？

运行时更新应调用：

graphInstance.updateOptions({ wheelEventAction: 'scroll' });

而不是只替换外部变量。

为什么改了默认节点颜色，旧节点没完全变化？

如果旧节点自身已经有 color，它会优先于默认值。默认值只在对象未设置对应字段时生效。

为什么 `layoutName: 'fixed'` 后节点没有自动排列？

这是预期行为。fixed 布局表示使用节点已有 x/y，不自动计算新坐标。

为什么打开 `performanceMode` 后自定义 DOM 分析不完整？

性能模式可能切换 EasyView 或只渲染部分 DOM。需要完整 DOM 分析、复杂截图或精细交互时，不建议开启性能模式。

图谱全局配置项（RGOptions）