配置与选项

relation-graph 库使用一个完整的选项系统（定义于 packages/types.ts:768-895）来配置图的行为、外观与交互性。该配置系统由以下部分组成：

• RGOptions：部分用户输入类型，接受任意子集的配置选项
• RGOptionsFull：完整的内部配置，所有属性均已定义（包含运行时状态）
• RGLayoutOptions：布局专用配置的联合类型（force、tree、center、circle 等）

所有平台（Vue2、Vue3、React、Svelte）都使用同一套核心选项系统：用户选项通过组件 props 传递给 RelationGraphCore，并在其中由 createDefaultConfig() 于 packages/relation-graph-models/data/RGOptionsDataUtils.ts:15-242 进行处理。

配置类型系统

核心配置类型与处理流水线

graph TB
    RGOptions["RGOptions
types.ts:894
(部分用户输入)"]
    RGOptionsFull["RGOptionsFull
types.ts:842-887
(完整内部配置)"]

    RGLayoutOptionsCore["RGLayoutOptionsCore
types.ts:478-484"]
    RGForceLayoutOptions["RGForceLayoutOptions
types.ts:495-502"]
    RGTreeLayoutOptions["RGTreeLayoutOptions
types.ts:517-532"]
    RGCenterLayoutOptions["RGCenterLayoutOptions
types.ts:509-513"]

    createDefaultConfig["createDefaultConfig()
RGOptionsDataUtils.ts:15"]
    appendDefaultOptions4Layout["appendDefaultOptions4Layout()
RGOptionsDataUtils.ts:269"]
    applyDefaultOptionsByLayout["applyDefaultOptionsByLayout()
RGOptionsDataUtils.ts:244"]

    RGOptions --> createDefaultConfig
    createDefaultConfig --> RGOptionsFull

    RGLayoutOptionsCore --> RGForceLayoutOptions
    RGLayoutOptionsCore --> RGTreeLayoutOptions
    RGLayoutOptionsCore --> RGCenterLayoutOptions
    RGForceLayoutOptions --> RGCenterLayoutOptions

    RGOptionsFull --> appendDefaultOptions4Layout
    appendDefaultOptions4Layout --> applyDefaultOptionsByLayout

    RGOptionsFull -.->|"包含"| RGLayoutOptionsCore

类型层级：

类型	定义	目的
RGOptions	Partial<RGOptionsInited> types.ts:894	用户输入，所有属性可选
RGOptionsFull	RGOptionsInited & {...runtime} types.ts:842	完整配置，包含运行时状态
RGLayoutOptionsCore	基础布局接口 types.ts:478	共享布局属性：layoutName、layoutDirection、fixedRootNode
RGForceLayoutOptions	扩展 core types.ts:495	力导物理：force_node_repulsion、force_line_elastic、maxLayoutTimes
RGTreeLayoutOptions	扩展 core types.ts:517	树形层级：from、treeNodeGapH、treeNodeGapV、levelGaps
RGCenterLayoutOptions	扩展 force types.ts:509	径向中心：distanceCoefficient、levelDistance

默认配置创建

createDefaultConfig() 函数会生成一个完整的 RGOptionsFull 对象，为所有属性填充默认值。

配置初始化流程

graph LR
    userOptions["userOptions: RGOptions"]
    createDefaultConfig["createDefaultConfig(userOptions)"]
    initDefaults["初始化 _options
填充所有默认值
lines 14-188"]
    mergeLoop["遍历用户选项键
lines 192-236"]
    handleObjects["处理对象：
layout、嵌套对象
lines 201-230"]
    handleArrays["处理数组：
深拷贝元素
lines 212-225"]
    handlePrimitives["处理基础类型：
直接赋值
line 234"]
    returnOptions["返回 RGOptionsFull"]

    userOptions --> createDefaultConfig
    createDefaultConfig --> initDefaults
    initDefaults --> mergeLoop
    mergeLoop --> handleObjects
    mergeLoop --> handleArrays
    mergeLoop --> handlePrimitives
    handleObjects --> returnOptions
    handleArrays --> returnOptions
    handlePrimitives --> returnOptions

位于 packages/relation-graph-models/data/RGOptionsDataUtils.ts:192-236 的合并过程会处理三种数据类型：

1. 对象 lines 201-230:

   • layout 对象：通过 JSON.parse(JSON.stringify()) 完整替换
   • 其他对象：对属性做浅合并
   • 对象中的数组：对每个元素做深拷贝

2. 数组 lines 212-225: 深拷贝每个元素，防止引用共享

3. 基础类型 line 234: 直接赋值

未知的选项 key 会通过 devLog() 输出警告，但仍会继续初始化流程 packages/relation-graph-models/data/RGOptionsDataUtils.ts:198。

核心选项分类

选项按功能分类组织，用于控制图的不同方面。

UI 显示选项

选项	类型	默认值	行号	说明
debug	boolean	true	19	通过 devLog() 启用调试日志
graphLoading	boolean	false	20	显示加载遮罩层
graphLoadingText	string	''	21	加载指示文本
showToolBar	boolean	true	22	显示工具栏组件
backgroundColor	string	'transparent'	23	画布背景色（CSS 值）
toolBarDirection	'v'|'h'	'v'	42	工具栏方向：竖向或横向
toolBarPositionH	'left'|'center'|'right'	'right'	43	工具栏水平对齐
toolBarPositionV	'top'|'center'|'bottom'	'center'	44	工具栏垂直对齐
viewHeight	string	'100%'	99	容器高度（CSS 值）
fullscreenElementXPath	string	''	29	全屏元素的 XPath
showMiniView	boolean	false	182	显示小地图导航视图

视觉样式选项

节点样式默认值

选项	类型	默认值	行号	说明
defaultNodeColor	string	'#ffffff'	45	节点背景色（CSS）
defaultNodeBorderColor	string	'#666666'	46	节点边框颜色（CSS）
defaultNodeBorderWidth	number	1	47	节点边框宽度（px）
defaultNodeBorderRadius	number	4	48	节点圆角半径（px）
defaultNodeShape	RGNodeShape	RGNodeShape.rect	49	节点形状：circle (0) 或 rect (1)
defaultNodeWidth	number	undefined	50	默认节点宽度（px）
defaultNodeHeight	number	undefined	51	默认节点高度（px）

连线样式默认值

选项	类型	默认值	行号	说明
defaultLineColor	string	'#cccccc'	53	线条描边颜色（CSS）
defaultLineWidth	number	2	54	线条描边宽度（px）
defaultLineShape	RGLineShape	StandardStraight	56	线条形状：1、4、6、44、49 等
defaultLineTextOffsetX	number	undefined	57	文本相对线条中心的水平偏移
defaultLineTextOffsetY	number	undefined	58	文本相对线条中心的垂直偏移
defaultJunctionPoint	RGJunctionPoint	border	61	连接点样式：border、tb、lr 等
defaultLineJunctionOffset	number	3	62	相对连接点的偏移（px）
defaultPolyLineRadius	number	5	63	直角折线拐角半径（px）
defaultLineTextOnPath	boolean	false	66	使用 SVG textPath 显示线条标签
lineTextMaxLength	number	66	67	线条文字最大长度（字符）
multiLineDistance	number	50	68	平行多线之间的间距（px）
defaultLineMarker	object	(arrow)	69-76	线条箭头默认 SVG marker

选择与交互样式

选项	类型	默认值	行号	说明
checkedItemBackgroundColor	string	undefined	24	选中项背景色（CSS）
defaultExpandHolderPosition	'hide'|'left'|'top'|…	'hide'	40	展开/收起按钮位置

交互控制选项

鼠标与触摸交互

选项	类型	默认值	行号	说明
disableWheelEvent	boolean	false	26	完全禁用鼠标滚轮事件
wheelEventAction	'zoom'|'scroll'|'none'	'zoom'	27	鼠标滚轮行为
dragEventAction	'move'|'selection'|'none'	'move'	28	画布拖拽行为
mouseWheelSpeed	number	10	94	鼠标滚轮缩放灵敏度
canvasMoveMode	boolean	false	32	启用画布平移模式（鼠标指针：grab）
selectionMode	boolean	false	25	启用多选模式

节点与连线拖拽

选项	类型	默认值	行号	说明
disableDragNode	boolean	false	30	禁用所有节点拖拽
disableDragLine	boolean	true	31	禁用连线拖拽/编辑
disableNodePointEvent	boolean	false	33	禁用节点点击/悬停事件
disableLinePointEvent	boolean	false	34	禁用连线点击/悬停事件

画布与视口选项

缩放控制

选项	类型	默认值	行号	说明
canvasZoom	number	100	93	当前缩放级别（百分比，私有）
minCanvasZoom	number	5	95	最小缩放级别（5%）
maxCanvasZoom	number	500	96	最大缩放级别（500%）

画布尺寸与位置

选项	类型	默认值	行号	说明
viewSize	object	{width: 300, height: 300}	77	视口容器尺寸
canvasSize	object	{width: 300, height: 300}	78-81	画布坐标空间尺寸
canvasOffset	object	{x: 25, y: 27}	82-85	画布相对视口原点的位置偏移
canvasOpacity	number	1	100	画布透明度（0-1，私有）

布局配置

layout 选项接受一个 RGLayoutOptions 对象，包含算法专用属性。基础属性在 RGLayoutOptionsCore types.ts:478-484 中定义：

核心布局选项（所有算法）

选项	类型	默认值	说明
layoutName	string	'center'	算法：'force'、'center'、'tree'、'circle'、'fixed'、'smart-tree'、'io-tree'、'folder'
layoutDirection	'h'|'v'	(varies)	布局方向：水平或垂直
fixedRootNode	boolean	true	根节点位置是否固定在 (0,0)
autoLayouting	boolean	false	当前是否正在自动布局（只读）
supportAutoLayout	boolean	(varies)	算法是否支持自动布局（只读）
alignItemsX	'start'|'center'|'end'	'center'	布局内节点水平对齐
alignItemsY	'start'|'center'|'end'	'center'	布局内节点垂直对齐

力导布局选项（RGForceLayoutOptions types.ts:495-502）：

选项	类型	默认值	说明
fastStart	boolean	false	跳过 center 布局初始化，使用随机位置
maxLayoutTimes	number	300	最大力导迭代次数
byNode	boolean	true	启用节点-节点斥力
byLine	boolean	true	启用连线弹性力
force_node_repulsion	number	1.0	节点斥力系数
force_line_elastic	number	1.0	连线弹性系数
force_x_coefficient	number	1.0	水平方向力乘数
force_y_coefficient	number	1.0	垂直方向力乘数

树布局选项（RGTreeLayoutOptions types.ts:517-532）：

选项	类型	默认值	说明
from	'left'|'right'|'top'|'bottom'	'left'	树根位置
treeNodeGapH	number	50	树节点之间的水平间距
treeNodeGapV	number	50	树节点之间的垂直间距
levelGaps	number[]	[]	按层级覆盖间距
layoutExpansionDirection	'start'|'center'|'end'	'start'	子节点展开方向
simpleTree	boolean	false	仅使用单向树展开
ignoreNodeSize	boolean	false	在布局中将所有节点视为同一尺寸

中心布局选项（RGCenterLayoutOptions types.ts:509-513）：

选项	类型	默认值	说明
distanceCoefficient	number	1.0	径向布局的距离缩放系数
levelDistance	number[]	[]	按层级覆盖半径
disableAsForceLayout	boolean	false	禁用力导物理（使用纯 center 布局）
(继承所有 force 选项)			Center 扩展 force 布局

Circle 布局选项：仅使用核心选项，将节点按圆形排列。

Fixed 布局选项：仅使用核心选项，保留输入数据中的节点位置。

性能选项

选项	类型	默认值	行号	说明
performanceMode	boolean	false	98	启用性能优化（私有）
showEasyView	boolean	false	97	使用基于 canvas 的简化渲染（私有）
enableNodeXYAnimation	boolean	false	37	启用节点位置变化的 CSS 过渡
enableCanvasTransformAnimation	boolean	false	38	启用画布缩放/平移的 CSS 过渡
reLayoutWhenExpandedOrCollapsed	boolean	false	39	节点展开/收起状态变化时自动触发布局

性能模式行为： 启用 performanceMode 后，系统会在大图（通常 >100 个节点）时自动切换到 Canvas2D 渲染。showEasyView 标志控制该渲染模式，并由系统自动管理。关于视口裁剪逻辑，见 packages/relation-graph-models/data/RGDataProvider.ts:129-143。

编辑功能选项

编辑状态标志

选项	类型	默认值	行号	说明
showReferenceLine	boolean	false	169	拖拽时显示对齐参考线
referenceLineAdsorption	boolean	false	170	启用吸附对齐行为
creatingSelection	boolean	false	101	当前正在创建选择框（私有）
creatingNodePlot	boolean	false	108	当前正在放置新节点（私有）
creatingLinePlot	boolean	false	111	当前正在绘制新连线（私有）
showTemplateNode	boolean	true	109	放置过程中显示节点预览

编辑控制器对象

这些对象用于存储正在进行的编辑操作的状态：

editingController [lines 153-160]：节点选择与多选状态

{
  show: boolean,        // 编辑 UI 是否可见
  nodes: RGNode[],      // 已选节点数组
  x: number,           // 选择框 X
  y: number,           // 选择框 Y
  width: number,       // 选择框宽度
  height: number       // 选择框高度
}

editingLineController [lines 133-152]：连线编辑状态

{
  show: boolean,             // 连线编辑 UI 是否可见
  line: RGLine | null,       // 正在编辑的连线
  startPoint: {x, y},        // 连线起点位置
  endPoint: {x, y},          // 连线终点位置
  text: {...},               // 文本标签位置
  ctrlPoints: [],            // 曲线控制点
  selectedLines: [],         // 多线选择
  line44Splits: [],          // 直角折线分段
  line49Points: [],          // 硬直角控制点
  ctrlPoint1: {x, y},        // 贝塞尔控制点 1
  ctrlPoint2: {x, y},        // 贝塞尔控制点 2
  toolbar: {x, y}            // 编辑工具栏位置
}

nodeConnectController [lines 161-168]：节点连线绘制状态

{
  show: boolean,       // 连接 UI 是否可见
  node: RGNode,        // 连接的源节点
  x: number,          // 连接 UI X
  y: number,          // 连接 UI Y
  width: number,      // 连接 UI 宽度
  height: number      // 连接 UI 高度
}

editingReferenceLine [lines 171-181]：对齐参考线状态

{
  show: boolean,       // 参考线是否可见
  directionV: boolean, // 垂直参考线激活
  directionH: boolean, // 水平参考线激活
  v_x, v_y, v_height,  // 垂直参考线位置
  h_x, h_y, h_width    // 水平参考线位置
}

连线 Marker 配置

defaultLineMarker 对象定义了连线箭头使用的默认 SVG marker [lines 69-76]：

defaultLineMarker: {
  viewBox: '0 0 12 12',    // SVG viewBox
  markerWidth: 20,          // Marker 显示宽度
  markerHeight: 20,         // Marker 显示高度
  refX: 3,                  // 参考点 X
  refY: 3,                  // 参考点 Y
  data: "M 0 0, V 6, L 4 3, Z"  // SVG path data
}

当 line.showStartArrow 或 line.showEndArrow 为 true 时将使用该 marker，除非被 line.startMarkerId 或 line.endMarkerId 覆盖。

模板选项

这些选项定义了交互式创建新节点与新连线时使用的模板：

newNodeTemplate [line 110]：通过 startCreatingNodePlot() 创建的新节点模板

newNodeTemplate: json2Node({
  id: 'rg-newNodeTemplate',
  x: 0,
  y: 0,
  text: ''
}, {})

newLineTemplate [lines 112-117]：通过 startCreatingLinePlot() 创建的新连线模板

newLineTemplate: {
  from: 'newRelationTemplate-from',
  to: 'newRelationTemplate-to',
  color: '',
  text: 'new line'
}

newLinkTemplate [lines 118-131]：连线绘制操作的内部状态

newLinkTemplate: {
  fromNode: null,           // 源节点
  toNodeObject: null,       // 目标节点（如存在）
  toNode: {                 // 用于预览的临时目标
    nothing: true,
    x: 400, y: 400,
    el_W: 30, el_H: 30
  },
  totalLinesBetweenNodes: 1,
  currentLineIndex: 0,
  line: {}
}

这些模板会经过 json2Node() 与 json2Line() 转换器处理，并且可在调用创建方法之前进行自定义。

内部状态选项（私有）

这些选项用于跟踪运行时状态，不应由用户直接设置：

选项	类型	默认值	行号	说明
instanceId	string	''	18	图实例的唯一标识
checkedNodeId	string	''	87	当前选中的节点 ID
checkedLineId	string	''	88	当前选中的连线 ID
draggingNodeId	string	''	89	当前正在拖拽的节点 ID
fullscreen	boolean	false	86	全屏模式是否激活
canvasOpacity	number	1	100	画布层透明度（0-1）
canvasZoom	number	100	93	当前缩放百分比
showEasyView	boolean	false	97	Canvas 渲染模式是否激活
performanceMode	boolean	false	98	性能优化是否激活
snapshotting	boolean	false	190	当前是否正在捕获图快照

小地图状态（miniViewVisibleHandle [lines 183-189]）：

miniViewVisibleHandle: {
  x: number,              // 小地图中可视视口 X
  y: number,              // 小地图中可视视口 Y
  width: number,          // 小地图中可视视口宽度
  height: number,         // 小地图中可视视口高度
  emptyContent: boolean   // 图是否没有可见内容
}

选择状态（selectionView [lines 102-107]）：

selectionView: {
  x: number,      // 选择框 X
  y: number,      // 选择框 Y
  width: number,  // 选择框宽度
  height: number  // 选择框高度
}

布局专用选项处理

有两个函数会根据 layout.layoutName 应用算法专用默认值：appendDefaultOptions4Layout() 与 applyDefaultOptionsByLayout()。它们在布局创建期间于 packages/relation-graph-models/models/RelationGraphWith6Layout.ts:338 被调用。

布局专用配置处理流水线

graph TB
    createLayout["createLayout()
RelationGraphWith6Layout.ts:335"]
    appendFn["appendDefaultOptions4Layout()
RGOptionsDataUtils.ts:269"]

    layoutNameCheck["根据
layoutOptions.layoutName
进行 switch"]

    centerCase["case: 'center'"]
    treeCase["case: includes('tree')"]
    fixedCase["case: 'fixed'"]
    forceCase["case: 'force'"]

    centerSet["layoutDirection = undefined"]

    treeFrom["检查 thisLayout.from"]
    treeTopBottom["'top' | 'bottom'"]
    treeLeftRight["'left' | 'right'"]

    treeSetV["layoutDirection = 'v'
levelGaps = []"]
    treeSetH["layoutDirection = 'h'
levelGaps = []"]

    fixedSet["layoutDirection = undefined"]

    instantiate["实例化布局类：
RGTreeLayout | RGCenterLayout
RGForceLayout | etc."]

    createLayout --> appendFn
    appendFn --> layoutNameCheck

    layoutNameCheck --> centerCase
    layoutNameCheck --> treeCase
    layoutNameCheck --> fixedCase
    layoutNameCheck --> forceCase

    centerCase --> centerSet
    treeCase --> treeFrom
    fixedCase --> fixedSet
    forceCase --> fixedSet

    treeFrom --> treeTopBottom
    treeFrom --> treeLeftRight
    treeTopBottom --> treeSetV
    treeLeftRight --> treeSetH

    centerSet --> instantiate
    treeSetV --> instantiate
    treeSetH --> instantiate
    fixedSet --> instantiate

appendDefaultOptions4Layout(layoutOptions) packages/relation-graph-models/data/RGOptionsDataUtils.ts:267-293 会修改布局对象：

• Center 布局 [line 271]：设置 layoutDirection = undefined
• Tree 布局 [lines 273-285]：
  • 若 from === 'top' || 'bottom'：设置 layoutDirection = 'v'
  • 若 from === 'left' || 'right'：设置 layoutDirection = 'h'
  • 若未定义则初始化 levelGaps 数组
• Fixed/Force 布局 [lines 287-290]：设置 layoutDirection = undefined
• 所有布局 [lines 291-292]：设置 supportAutoLayout = false、autoLayouting = false

布局方向与连接点配置

布局类型	layoutDirection	defaultJunctionPoint	说明
Center	undefined	border	使用径向定位
Tree (top/bottom)	'v'	tb	垂直层级
Tree (left/right)	'h'	lr	水平层级
Force	undefined	border	基于物理，无固有方向
Fixed	undefined	border	保留输入位置
Circle	undefined	border	圆形排列

appendDefaultOptions4Layout(layoutOptions) RGOptionsDataUtils.ts:269-294：

• 原地修改 layoutOptions 对象
• 根据算法与方向设置 layoutDirection
• 为 tree 布局初始化 levelGaps 数组
• 当前已注释掉：设置 supportAutoLayout 与 autoLayouting 标志

applyDefaultOptionsByLayout(thisLayout, _options) RGOptionsDataUtils.ts:244-268：

• 根据布局算法修改主 _options 对象
• 根据布局类型与方向设置 defaultJunctionPoint
• 当前大多已注释掉（连接点在别处设置）

运行时选项更新

选项可通过公共 API 在运行时更新，并会流经多个校验与处理层。

选项更新流水线

graph TB
    userCall["graphInstance.setOptions(options)
RelationGraphWith99API.ts:28"]
    apiMethod["setOptions(options)
调用 _updateOptions()"]
    updateMethod["_updateOptions(options)
RelationGraphWith3Options1Update.ts:21"]

    validateLayouts["若存在 options['layouts'] 则拒绝
line 25-27"]
    fixTypos["修复拼写：defaultPloyLineRadius
→ defaultPolyLineRadius
line 29-31"]
    debugFlag["设置 window.relationGraphDebug
当 debug === true 时
line 32-40"]

    applyLayoutDefaults["appendDefaultOptions4Layout()
applyDefaultOptionsByLayout()
line 41-43"]

    dataProviderUpdate["dataProvider.updateOptions()
RGDataProvider.ts:123"]
    objectAssign["Object.assign(this.options, options)
line 128"]

    perfModeCheck["if (performanceMode) 检查：
canvasZoom, viewSize, canvasOffset
line 129-144"]
    setCommits["commits.optionsChanged = true
line 145"]
    callHook["updateViewHook(commits)
line 120"]

    frameworkUpdate["框架专用
响应式更新"]

    userCall --> apiMethod
    apiMethod --> updateMethod
    updateMethod --> validateLayouts
    validateLayouts --> fixTypos
    fixTypos --> debugFlag
    debugFlag --> applyLayoutDefaults
    applyLayoutDefaults --> dataProviderUpdate
    dataProviderUpdate --> objectAssign
    objectAssign --> perfModeCheck
    perfModeCheck --> setCommits
    setCommits --> callHook
    callHook --> frameworkUpdate

逐层处理：

1. API 层 RelationGraphWith99API.ts:28-40:

   • setOptions(options: RGOptions)：全量替换选项（调用 _updateOptions）
   • updateOptions(options: Partial<RGOptionsFull>)：局部更新（已废弃，与 setOptions 相同）

2. 校验层 RelationGraphWith3Options1Update.ts:21-46:

   • Line 25-27：若存在 options['layouts'] 则抛错（layout 的常见拼写错误）
   • Line 29-31：自动修复 defaultPloyLineRadius → defaultPolyLineRadius
   • Line 32-40：当 debug: true 时设置全局 window.relationGraphDebug 标志
   • Line 41-43：通过辅助函数应用布局专用默认值

3. 数据提供者层 RGDataProvider.ts:123-146:

   • Line 128：通过 Object.assign(this.options, options) 合并选项
   • Line 129-144：在性能模式下跟踪特定属性变化：
     • canvasZoom：设置 commits.nodesListChanged 与 commits.linesListChanged
     • viewSize：设置 commits.nodesListChanged 与 commits.linesListChanged
     • canvasOffset：设置 commits.nodesListChanged 与 commits.linesListChanged
   • Line 145：总是设置 commits.optionsChanged = true
   • Line 120：调用 updateViewHook(commits) 触发框架更新

使用示例：

// 更新布局算法
graphInstance.setOptions({
  layout: { layoutName: 'force', force_node_repulsion: 2 }
});

// 更新视觉样式
graphInstance.setOptions({
  defaultNodeColor: '#ff0000',
  defaultLineColor: '#0000ff'
});

// 更新缩放级别（在性能模式下会触发节点/连线重新渲染）
graphInstance.setOptions({
  canvasZoom: 150
});

// 禁用用户交互
graphInstance.setOptions({
  disableDragNode: true,
  disableWheelEvent: true
});

数据转换中的选项

选项会传递给 json2Node() 与 json2Line() 转换器，以便在从用户输入创建运行时对象时应用默认样式。

连线数据转换流水线

graph LR
    jsonLine["JsonLine 输入"]
    json2Line["json2Line(jsonLine, options)
RGLineDataUtils.ts:3"]

    validateFrom["校验 from 字段
必须为 string (nodeId)
line 4-18"]
    validateTo["校验 to 字段
必须为 string (nodeId)
line 4-18"]

    handleDeprecated["处理已废弃字段：
isShow → hidden
isHide → hidden
line 20-27"]

    applyDefaults["应用选项默认值：
lineShape = options.defaultLineShape
line 50"]

    setTypes["设置 fromType/toType：
Node vs CanvasPoint
line 37-38"]

    createRGLine["返回 RGLine 对象
line 31-84"]

    jsonLine --> json2Line
    json2Line --> validateFrom
    validateFrom --> validateTo
    validateTo --> handleDeprecated
    handleDeprecated --> applyDefaults
    applyDefaults --> setTypes
    setTypes --> createRGLine

节点数据转换流水线

graph LR
    jsonNode["JsonNode 输入"]
    json2Node["json2Node(jsonNode, options, sizeMap)
RGNodeDataUtils.ts:10"]

    validateId["校验 id 字段
必须存在
line 11-14"]

    handleDeprecated["处理已废弃字段：
isShow → hidden
isHide → hidden
line 15-22"]

    applyDefaults["应用选项默认值：
nodeShape = options.defaultNodeShape
width = options.defaultNodeWidth
height = options.defaultNodeHeight
line 23-36"]

    lookupSize["查找缓存尺寸：
来自 nodesSizeMap
line 74-86"]

    createRGNode["返回 RGNode 对象
line 27-93"]

    jsonNode --> json2Node
    json2Node --> validateId
    validateId --> handleDeprecated
    handleDeprecated --> applyDefaults
    applyDefaults --> lookupSize
    lookupSize --> createRGNode

连线转换中的选项应用 RGLineDataUtils.ts:3-86：

json2Line() 函数会从 RGOptions 中应用默认值：

属性	默认值来源	回退值	行号
lineShape	options.defaultLineShape	1 (StandardStraight)	50
type	—	'line'	35
fromType	—	Node 或 CanvasPoint	37
toType	—	Node 或 CanvasPoint	38
showStartArrow	—	false	56
showEndArrow	—	true	57

节点转换中的选项应用 RGNodeDataUtils.ts:10-95：

json2Node() 函数会从 RGOptions 中应用默认值：

属性	默认值来源	回退值	行号
nodeShape	options.defaultNodeShape	RGNodeShape.rect (1)	36
width	options.defaultNodeWidth	undefined	23
height	options.defaultNodeHeight	undefined	24
type	—	'node'	30
expanded	—	true	32
el_W	nodesSizeMap 或 width	0	70
el_H	nodesSizeMap 或 height	0	71

两个转换器都会：

• 处理已废弃的 isShow/isHide 属性，并转换为 hidden
• 初始化运行时属性（lot、rgCalcedVisibility、rgShouldRender）
• 校验必填字段，并在数据无效时抛出错误

选项校验与错误处理

配置系统会在多个阶段对选项进行校验，以捕获错误并提供更有帮助的信息。

校验阶段：

1. 更新时校验 RelationGraphWith3Options1Update.ts:21-46

// 拒绝复数形式 'layouts'（常见拼写错误）
if (_newOptions['layouts']) {
  throw new Error('Graph options do not support setting layouts properties !');
}

// 自动修复拼写错误
if (_newOptions.defaultPloyLineRadius) {
  _newOptions.defaultPolyLineRadius = _newOptions.defaultPloyLineRadius;
}

2. 合并时校验 RGOptionsDataUtils.ts:194-239

在 createDefaultConfig() 期间，未知的选项 key 会被记录日志但忽略：

if (!optionsKeys.includes(key)) {
  devLog('RGOptions: unknow option key:', key);
  return; // 跳过该 key
}

3. json2Line() 与 json2Node() 中的数据校验

连线需要有效的 from 与 to 节点 ID：

// RGLineDataUtils.ts:4-18
if (originData.from === undefined) {
  throw new Error('error,line must has option[from]:');
}
if (typeof originData.from !== 'string') {
  throw new TypeError('error line from, must be string:');
}

节点需要唯一的 id：

// RGNodeDataUtils.ts:11-14
if (originData.id === undefined) {
  throw new Error('node must has option[id]:');
}

错误处理策略：

错误类型	动作	位置
无效布局名称	抛出错误	createLayout() With6Layout.ts:359
缺少节点/连线 ID	抛出错误	数据转换器
未知选项 key	记录警告并跳过	createDefaultConfig() RGOptionsDataUtils.ts:200
常见拼写错误	自动修复	_updateOptions() With3Options1Update.ts:29
无效属性类型	抛出错误	数据转换器

平台集成

每个平台组件都通过 props 接受 RGOptions，并创建一个平台专用的数据提供者以桥接到 RelationGraphCore。

平台配置流程

graph TB
    userVue2["Vue2:
<RelationGraph :options='opts' />"]
    userVue3["Vue3:
<RelationGraph :options='opts' />"]
    userReact["React:
<RelationGraph options={opts} />"]
    userSvelte["Svelte:
<RelationGraph options={opts} />"]

    vue2Comp["core4vue/index.vue
组件"]
    vue3Comp["core4vue3/index.vue
组件"]
    reactComp["RelationGraph.tsx
组件"]
    svelteComp["RelationGraph.svelte
组件"]

    vue2Init["createDataProvider4Vue2()
RGDataProvider4Vue2.ts:12"]
    vue3Init["createDataProvider4Vue3()
RGDataProvider4Vue3.ts:12"]
    reactInit["new RGDataProvider4React()
RGDataProvider4React.ts:12"]
    svelteInit["new RGDataProvider4Svelte()
RGDataProvider4Svelte.ts:12"]

    coreInit["new RelationGraphCore(options)
RelationGraphCore.ts"]
    optionsLayer["RelationGraphWith3Options1Update
_updateOptions()"]

    userVue2 --> vue2Comp
    userVue3 --> vue3Comp
    userReact --> reactComp
    userSvelte --> svelteComp

    vue2Comp --> vue2Init
    vue3Comp --> vue3Init
    reactComp --> reactInit
    svelteComp --> svelteInit

    vue2Init --> coreInit
    vue3Init --> coreInit
    reactInit --> coreInit
    svelteInit --> coreInit

    coreInit --> optionsLayer

平台专用数据提供者创建：

平台	数据提供者	响应式机制	文件
Vue 2	RGDataProvider4Vue2	通过 Vue.set() 实现深层响应式	RGDataProvider4Vue2.ts:12-51
Vue 3	RGDataProvider4Vue3	reactive()、ref() store	RGDataProvider4Vue3.ts:12-49
React	RGDataProvider4React	setState() 回调	RGDataProvider4React.ts:12-38
Svelte	RGDataProvider4Svelte	writable() store	RGDataProvider4Svelte.ts:12-44

示例：Vue3 数据提供者创建 RGDataProvider4Vue3.ts:12-49

export const createDataProvider4Vue3 = (options: Rpartial<RGOptionsFull>) => {
  // 创建响应式 store
  const optionsRef = reactive(createDefaultConfig(options));
  const shouldRenderNodesRef = ref([]);
  const shouldRenderLinesRef = ref([]);
  const shouldRenderFakeLinesRef = ref([]);

  // 使用响应式 store 创建数据提供者
  const dataProvider = new RGDataProvider();
  dataProvider.options = optionsRef;
  dataProvider.runtimeDATA4ShouldRenderItems.nodes = shouldRenderNodesRef.value;
  dataProvider.runtimeDATA4ShouldRenderItems.lines = shouldRenderLinesRef.value;
  dataProvider.runtimeDATA4ShouldRenderItems.fakeLines = shouldRenderFakeLinesRef.value;

  // 设置更新钩子
  dataProvider.updateViewHook = (commits) => {
    // Vue3 的响应式会自动触发更新
  };

  return dataProvider;
};

所有平台最终都会调用 createDefaultConfig(options) RGOptionsDataUtils.ts:15 来创建完整配置，然后将其包装进框架专用的响应式系统中。

配置分类

配置系统会将选项组织为逻辑分类，以控制图行为与外观的不同方面。

主要配置分类

分类	选项数量	关键示例	目的
UI Control	~15	showToolBar、showDebugPanel、fullscreen	控制界面可见性
Visual Styling	~20	backgroundColor、defaultNodeColor、defaultLineMarker	定义外观
User Interaction	~12	disableDragNode、selectionMode、wheelEventAction	配置用户控制
Canvas Management	~8	canvasSize、canvasOffset、canvasZoom	管理视口
Layout Control	~1 + 子选项	layout 对象及其算法专用属性	控制定位
Performance	~5	performanceMode、showEasyView、enableNodeXYAnimation	优化渲染
Editing Features	~10	各类 editing*Controller 对象	启用交互式编辑

关键配置初始化

graph LR
    INSTANCE_ID["instanceId 生成
RGIns-{index}"]
    TEMPLATE_INIT["模板初始化
newNodeTemplate
newLineTemplate"]
    CONTROLLER_SETUP["控制器初始化
editingController
editingLineController"]
    VIEW_CONFIG["视图配置
viewSize, viewELSize
canvasNVInfo"]

    INSTANCE_ID --> TEMPLATE_INIT
    TEMPLATE_INIT --> CONTROLLER_SETUP
    CONTROLLER_SETUP --> VIEW_CONFIG

    style INSTANCE_ID fill:#e8f5e8
    style VIEW_CONFIG fill:#e1f5fe

newInstanceOptions() 函数确保每个图实例都获得唯一标识，并正确初始化各配置对象，从而避免跨实例相互干扰。