JavaScript is required
relation-graph Relational Data Visualization and Editing
Sign in 中文 GitHub

Configuration & Options

The relation-graph library uses a comprehensive options system defined in packages/types.ts:768-895 to configure graph behavior, appearance, and interactivity. The configuration system consists of:

  • RGOptions: Partial user input type accepting any subset of configuration options
  • RGOptionsFull: Complete internal configuration with all properties defined, including runtime state
  • RGLayoutOptions: Union type for layout-specific configurations (force, tree, center, circle, etc.)

All platforms (Vue2, Vue3, React, Svelte) use the same core options system, passing user options through component props to RelationGraphCore, where they are processed by createDefaultConfig() at packages/relation-graph-models/data/RGOptionsDataUtils.ts:15-242.

Configuration Type System

Core Configuration Types and Processing Pipeline

graph TB
    RGOptions["RGOptions
types.ts:894
(Partial user input)"]
    RGOptionsFull["RGOptionsFull
types.ts:842-887
(Complete internal config)"]
    
    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 -.->|"contains"| RGLayoutOptionsCore

Type Hierarchy:

Type Definition Purpose
RGOptions Partial<RGOptionsInited> types.ts:894 User input, all properties optional
RGOptionsFull RGOptionsInited & {...runtime} types.ts:842 Complete config with runtime state
RGLayoutOptionsCore Base layout interface types.ts:478 Shared layout properties: layoutName, layoutDirection, fixedRootNode
RGForceLayoutOptions Extends core types.ts:495 Force physics: force_node_repulsion, force_line_elastic, maxLayoutTimes
RGTreeLayoutOptions Extends core types.ts:517 Tree hierarchy: from, treeNodeGapH, treeNodeGapV, levelGaps
RGCenterLayoutOptions Extends force types.ts:509 Radial center: distanceCoefficient, levelDistance

Default Configuration Creation

The createDefaultConfig() function generates a complete RGOptionsFull object with defaults for all properties.

Configuration Initialization Flow

graph LR
    userOptions["userOptions: RGOptions"]
    createDefaultConfig["createDefaultConfig(userOptions)"]
    initDefaults["Initialize _options
with all default values
lines 14-188"]
    mergeLoop["Iterate user option keys
lines 192-236"]
    handleObjects["Handle objects:
layout, nested objects
lines 201-230"]
    handleArrays["Handle arrays:
deep copy elements
lines 212-225"]
    handlePrimitives["Handle primitives:
direct assignment
line 234"]
    returnOptions["Return RGOptionsFull"]
    
    userOptions --> createDefaultConfig
    createDefaultConfig --> initDefaults
    initDefaults --> mergeLoop
    mergeLoop --> handleObjects
    mergeLoop --> handleArrays
    mergeLoop --> handlePrimitives
    handleObjects --> returnOptions
    handleArrays --> returnOptions
    handlePrimitives --> returnOptions

The merging process at packages/relation-graph-models/data/RGOptionsDataUtils.ts:192-236 handles three data types:

  1. Objects lines 201-230:

    • layout object: Full replacement via JSON.parse(JSON.stringify())
    • Other objects: Shallow merge of properties
    • Arrays within objects: Deep copy each element

  2. Arrays lines 212-225: Deep copy each element to prevent reference sharing

  3. Primitives line 234: Direct assignment

Unknown option keys log a warning via devLog() but allow initialization to continue packages/relation-graph-models/data/RGOptionsDataUtils.ts:198.

Core Option Categories

Options are organized into functional categories controlling different aspects of the graph.

UI Display Options

Option Type Default Line Description
debug boolean true 19 Enable debug logging via devLog()
graphLoading boolean false 20 Show loading overlay
graphLoadingText string '' 21 Loading indicator text
showToolBar boolean true 22 Display toolbar widget
backgroundColor string 'transparent' 23 Canvas background color (CSS value)
toolBarDirection 'v'|'h' 'v' 42 Toolbar orientation: vertical or horizontal
toolBarPositionH 'left'|'center'|'right' 'right' 43 Horizontal toolbar alignment
toolBarPositionV 'top'|'center'|'bottom' 'center' 44 Vertical toolbar alignment
viewHeight string '100%' 99 Container height (CSS value)
fullscreenElementXPath string '' 29 XPath for fullscreen element
showMiniView boolean false 182 Display mini-map navigation view

Visual Styling Options

Node Styling Defaults

Option Type Default Line Description
defaultNodeColor string '#ffffff' 45 Node background color (CSS)
defaultNodeBorderColor string '#666666' 46 Node border color (CSS)
defaultNodeBorderWidth number 1 47 Node border width (px)
defaultNodeBorderRadius number 4 48 Node border radius (px)
defaultNodeShape RGNodeShape RGNodeShape.rect 49 Node shape: circle (0) or rect (1)
defaultNodeWidth number undefined 50 Default node width (px)
defaultNodeHeight number undefined 51 Default node height (px)

Line Styling Defaults

Option Type Default Line Description
defaultLineColor string '#cccccc' 53 Line stroke color (CSS)
defaultLineWidth number 2 54 Line stroke width (px)
defaultLineShape RGLineShape StandardStraight 56 Line shape: 1, 4, 6, 44, 49, etc.
defaultLineTextOffsetX number undefined 57 Horizontal text offset from line center
defaultLineTextOffsetY number undefined 58 Vertical text offset from line center
defaultJunctionPoint RGJunctionPoint border 61 Connection point style: border, tb, lr, etc.
defaultLineJunctionOffset number 3 62 Offset from junction point (px)
defaultPolyLineRadius number 5 63 Corner radius for orthogonal lines (px)
defaultLineTextOnPath boolean false 66 Use SVG textPath for line labels
lineTextMaxLength number 66 67 Maximum line text length (chars)
multiLineDistance number 50 68 Spacing between parallel lines (px)
defaultLineMarker object (arrow) 69-76 Default SVG marker for line arrows

Selection & Interaction Styling

Option Type Default Line Description
checkedItemBackgroundColor string undefined 24 Background color for selected items (CSS)
defaultExpandHolderPosition 'hide'|'left'|'top'|… 'hide' 40 Position of expand/collapse button

Interaction Control Options

Mouse & Touch Interaction

Option Type Default Line Description
disableWheelEvent boolean false 26 Disable mouse wheel events entirely
wheelEventAction 'zoom'|'scroll'|'none' 'zoom' 27 Mouse wheel behavior
dragEventAction 'move'|'selection'|'none' 'move' 28 Canvas drag behavior
mouseWheelSpeed number 10 94 Mouse wheel zoom sensitivity
canvasMoveMode boolean false 32 Enable canvas panning mode (cursor: grab)
selectionMode boolean false 25 Enable multi-select mode

Node & Line Dragging

Option Type Default Line Description
disableDragNode boolean false 30 Disable all node dragging
disableDragLine boolean true 31 Disable line dragging/editing
disableNodePointEvent boolean false 33 Disable node click/hover events
disableLinePointEvent boolean false 34 Disable line click/hover events

Canvas & Viewport Options

Zoom Control

Option Type Default Line Description
canvasZoom number 100 93 Current zoom level (percentage, private)
minCanvasZoom number 5 95 Minimum zoom level (5%)
maxCanvasZoom number 500 96 Maximum zoom level (500%)

Canvas Dimensions & Position

Option Type Default Line Description
viewSize object {width: 300, height: 300} 77 Viewport container dimensions
canvasSize object {width: 300, height: 300} 78-81 Canvas coordinate space dimensions
canvasOffset object {x: 25, y: 27} 82-85 Canvas position offset from viewport origin
canvasOpacity number 1 100 Canvas opacity (0-1, private)

Layout Configuration

The layout option accepts an RGLayoutOptions object with algorithm-specific properties. Base properties defined in RGLayoutOptionsCore types.ts:478-484:

Core Layout Options (All Algorithms)

Option Type Default Description
layoutName string 'center' Algorithm: 'force', 'center', 'tree', 'circle', 'fixed', 'smart-tree', 'io-tree', 'folder'
layoutDirection 'h'|'v' (varies) Layout orientation: horizontal or vertical
fixedRootNode boolean true Whether root node position is fixed at (0,0)
autoLayouting boolean false Whether auto-layout is currently running (read-only)
supportAutoLayout boolean (varies) Whether algorithm supports auto-layout (read-only)
alignItemsX 'start'|'center'|'end' 'center' Horizontal node alignment within layout
alignItemsY 'start'|'center'|'end' 'center' Vertical node alignment within layout

Force Layout Options (RGForceLayoutOptions types.ts:495-502):

Option Type Default Description
fastStart boolean false Skip center layout initialization, use random positions
maxLayoutTimes number 300 Maximum force iterations
byNode boolean true Enable node-node repulsion
byLine boolean true Enable line elastic forces
force_node_repulsion number 1.0 Node repulsion coefficient
force_line_elastic number 1.0 Line elastic coefficient
force_x_coefficient number 1.0 Horizontal force multiplier
force_y_coefficient number 1.0 Vertical force multiplier

Tree Layout Options (RGTreeLayoutOptions types.ts:517-532):

Option Type Default Description
from 'left'|'right'|'top'|'bottom' 'left' Tree root position
treeNodeGapH number 50 Horizontal gap between tree nodes
treeNodeGapV number 50 Vertical gap between tree nodes
levelGaps number[] [] Per-level gap overrides
layoutExpansionDirection 'start'|'center'|'end' 'start' Direction of child expansion
simpleTree boolean false Use unidirectional tree expansion only
ignoreNodeSize boolean false Treat all nodes as same size in layout

Center Layout Options (RGCenterLayoutOptions types.ts:509-513):

Option Type Default Description
distanceCoefficient number 1.0 Distance scaling factor for radial layout
levelDistance number[] [] Per-level radius overrides
disableAsForceLayout boolean false Disable force physics (use pure center layout)
(inherits all force options) Center extends force layout

Circle Layout Options: Uses core options only, arranges nodes in circular pattern.

Fixed Layout Options: Uses core options only, preserves node positions from input data.

Performance Options

Option Type Default Line Description
performanceMode boolean false 98 Enable performance optimizations (private)
showEasyView boolean false 97 Use canvas-based simplified rendering (private)
enableNodeXYAnimation boolean false 37 Enable CSS transitions for node position changes
enableCanvasTransformAnimation boolean false 38 Enable CSS transitions for canvas zoom/pan
reLayoutWhenExpandedOrCollapsed boolean false 39 Automatically trigger layout when node expand state changes

Performance Mode Behavior: When performanceMode is enabled, the system automatically switches to Canvas2D rendering for large graphs (typically >100 nodes). The showEasyView flag controls this rendering mode and is managed automatically. See packages/relation-graph-models/data/RGDataProvider.ts:129-143 for viewport culling logic.

Editing Feature Options

Editing State Flags

Option Type Default Line Description
showReferenceLine boolean false 169 Show alignment guide lines during drag
referenceLineAdsorption boolean false 170 Enable snap-to-align behavior
creatingSelection boolean false 101 Currently creating selection box (private)
creatingNodePlot boolean false 108 Currently placing new node (private)
creatingLinePlot boolean false 111 Currently drawing new line (private)
showTemplateNode boolean true 109 Show node preview during placement

Editing Controller Objects

These objects store the state of active editing operations:

editingController [lines 153-160]: Node selection and multi-select state

{
  show: boolean,        // Whether editing UI is visible
  nodes: RGNode[],      // Selected nodes array
  x: number,           // Selection box X
  y: number,           // Selection box Y  
  width: number,       // Selection box width
  height: number       // Selection box height
}

editingLineController [lines 133-152]: Line editing state

{
  show: boolean,             // Whether line editing UI is visible
  line: RGLine | null,       // Line being edited
  startPoint: {x, y},        // Line start position
  endPoint: {x, y},          // Line end position
  text: {...},               // Text label position
  ctrlPoints: [],            // Control points for curves
  selectedLines: [],         // Multi-line selection
  line44Splits: [],          // Orthogonal line segments
  line49Points: [],          // Hard orthogonal control points
  ctrlPoint1: {x, y},        // Bezier control point 1
  ctrlPoint2: {x, y},        // Bezier control point 2
  toolbar: {x, y}            // Editing toolbar position
}

nodeConnectController [lines 161-168]: Node connection drawing state

{
  show: boolean,       // Whether connect UI is visible
  node: RGNode,        // Source node for connection
  x: number,          // Connect UI X
  y: number,          // Connect UI Y
  width: number,      // Connect UI width
  height: number      // Connect UI height
}

editingReferenceLine [lines 171-181]: Alignment guide state

{
  show: boolean,       // Whether guides are visible
  directionV: boolean, // Vertical guide active
  directionH: boolean, // Horizontal guide active
  v_x, v_y, v_height,  // Vertical guide position
  h_x, h_y, h_width    // Horizontal guide position
}

Line Marker Configuration

The defaultLineMarker object defines the default SVG marker used for line arrows [lines 69-76]:

defaultLineMarker: {
  viewBox: '0 0 12 12',    // SVG viewBox
  markerWidth: 20,          // Marker display width
  markerHeight: 20,         // Marker display height
  refX: 3,                  // Reference point X
  refY: 3,                  // Reference point Y
  data: "M 0 0, V 6, L 4 3, Z"  // SVG path data
}

This marker is used when line.showStartArrow or line.showEndArrow is true, unless overridden by line.startMarkerId or line.endMarkerId.

Template Options

These options define templates used when creating new nodes and lines interactively:

newNodeTemplate [line 110]: Template for new nodes created via startCreatingNodePlot()

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

newLineTemplate [lines 112-117]: Template for new lines created via startCreatingLinePlot()

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

newLinkTemplate [lines 118-131]: Internal state for line drawing operations

newLinkTemplate: {
  fromNode: null,           // Source node
  toNodeObject: null,       // Target node (if exists)
  toNode: {                 // Temporary target for preview
    nothing: true,
    x: 400, y: 400,
    el_W: 30, el_H: 30
  },
  totalLinesBetweenNodes: 1,
  currentLineIndex: 0,
  line: {}
}

These templates are processed through json2Node() and json2Line() converters and can be customized before calling creation methods.

Internal State Options (Private)

These options track runtime state and should not be set directly by users:

Option Type Default Line Description
instanceId string '' 18 Unique graph instance identifier
checkedNodeId string '' 87 Currently selected node ID
checkedLineId string '' 88 Currently selected line ID
draggingNodeId string '' 89 Currently dragging node ID
fullscreen boolean false 86 Fullscreen mode active
canvasOpacity number 1 100 Canvas layer opacity (0-1)
canvasZoom number 100 93 Current zoom percentage
showEasyView boolean false 97 Canvas rendering mode active
performanceMode boolean false 98 Performance optimizations active
snapshotting boolean false 190 Currently capturing graph snapshot

Mini-View State (miniViewVisibleHandle [lines 183-189]):

miniViewVisibleHandle: {
  x: number,              // Visible viewport X on mini-map
  y: number,              // Visible viewport Y on mini-map
  width: number,          // Visible viewport width on mini-map
  height: number,         // Visible viewport height on mini-map
  emptyContent: boolean   // Whether graph has no visible content
}

Selection State (selectionView [lines 102-107]):

selectionView: {
  x: number,      // Selection box X
  y: number,      // Selection box Y
  width: number,  // Selection box width
  height: number  // Selection box height
}

Layout-Specific Option Processing

Two functions apply algorithm-specific defaults based on layout.layoutName: appendDefaultOptions4Layout() and applyDefaultOptionsByLayout(). These are called during layout creation at packages/relation-graph-models/models/RelationGraphWith6Layout.ts:338.

Layout-Specific Configuration Processing Pipeline

graph TB
    createLayout["createLayout()
RelationGraphWith6Layout.ts:335"]
    appendFn["appendDefaultOptions4Layout()
RGOptionsDataUtils.ts:269"]
    
    layoutNameCheck["Switch on
layoutOptions.layoutName"]
    
    centerCase["case: 'center'"]
    treeCase["case: includes('tree')"]
    fixedCase["case: 'fixed'"]
    forceCase["case: 'force'"]
    
    centerSet["layoutDirection = undefined"]
    
    treeFrom["Check thisLayout.from"]
    treeTopBottom["'top' | 'bottom'"]
    treeLeftRight["'left' | 'right'"]
    
    treeSetV["layoutDirection = 'v'
levelGaps = []"]
    treeSetH["layoutDirection = 'h'
levelGaps = []"]
    
    fixedSet["layoutDirection = undefined"]
    
    instantiate["Instantiate layout class:
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 modifies the layout object:

  • Center layout [line 271]: Sets layoutDirection = undefined
  • Tree layouts [lines 273-285]:
    • If from === 'top' || 'bottom': Sets layoutDirection = 'v'
    • If from === 'left' || 'right': Sets layoutDirection = 'h'
    • Initializes levelGaps array if undefined
  • Fixed/Force layouts [lines 287-290]: Sets layoutDirection = undefined
  • All layouts [lines 291-292]: Sets supportAutoLayout = false, autoLayouting = false

Layout Direction and Junction Point Configuration

Layout Type layoutDirection defaultJunctionPoint Notes
Center undefined border Uses radial positioning
Tree (top/bottom) 'v' tb Vertical hierarchy
Tree (left/right) 'h' lr Horizontal hierarchy
Force undefined border Physics-based, no inherent direction
Fixed undefined border Preserves input positions
Circle undefined border Circular arrangement

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

  • Modifies the layoutOptions object in-place
  • Sets layoutDirection based on algorithm and orientation
  • Initializes levelGaps array for tree layouts
  • Currently commented out: Sets supportAutoLayout and autoLayouting flags

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

  • Modifies main _options object based on layout algorithm
  • Sets defaultJunctionPoint based on layout type and direction
  • Currently mostly commented out (junction points are set elsewhere)

Runtime Option Updates

Options are updated at runtime through the public API, flowing through multiple validation and processing layers.

Option Update Pipeline

graph TB
    userCall["graphInstance.setOptions(options)
RelationGraphWith99API.ts:28"]
    apiMethod["setOptions(options)
calls _updateOptions()"]
    updateMethod["_updateOptions(options)
RelationGraphWith3Options1Update.ts:21"]
    
    validateLayouts["Reject if options['layouts'] exists
line 25-27"]
    fixTypos["Fix typo: defaultPloyLineRadius
→ defaultPolyLineRadius
line 29-31"]
    debugFlag["Set window.relationGraphDebug
if 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) check:
canvasZoom, viewSize, canvasOffset
line 129-144"]
    setCommits["commits.optionsChanged = true
line 145"]
    callHook["updateViewHook(commits)
line 120"]
    
    frameworkUpdate["Framework-specific
reactive update"]
    
    userCall --> apiMethod
    apiMethod --> updateMethod
    updateMethod --> validateLayouts
    validateLayouts --> fixTypos
    fixTypos --> debugFlag
    debugFlag --> applyLayoutDefaults
    applyLayoutDefaults --> dataProviderUpdate
    dataProviderUpdate --> objectAssign
    objectAssign --> perfModeCheck
    perfModeCheck --> setCommits
    setCommits --> callHook
    callHook --> frameworkUpdate

Layer-by-Layer Processing:

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

    • setOptions(options: RGOptions): Full options replacement (calls _updateOptions)
    • updateOptions(options: Partial<RGOptionsFull>): Partial update (deprecated, same as setOptions)

  2. Validation Layer RelationGraphWith3Options1Update.ts:21-46:

    • Line 25-27: Throws error if options['layouts'] exists (common typo for layout)
    • Line 29-31: Auto-fixes defaultPloyLineRadius → defaultPolyLineRadius
    • Line 32-40: Sets global window.relationGraphDebug flag if debug: true
    • Line 41-43: Applies layout-specific defaults via helper functions

  3. Data Provider Layer RGDataProvider.ts:123-146:

    • Line 128: Merges options via Object.assign(this.options, options)
    • Line 129-144: In performance mode, tracks specific property changes:
      • canvasZoom: Sets commits.nodesListChanged and commits.linesListChanged
      • viewSize: Sets commits.nodesListChanged and commits.linesListChanged
      • canvasOffset: Sets commits.nodesListChanged and commits.linesListChanged
    • Line 145: Always sets commits.optionsChanged = true
    • Line 120: Calls updateViewHook(commits) to trigger framework update

Usage Examples:

// Update layout algorithm
graphInstance.setOptions({
  layout: { layoutName: 'force', force_node_repulsion: 2 }
});

// Update visual styling
graphInstance.setOptions({
  defaultNodeColor: '#ff0000',
  defaultLineColor: '#0000ff'
});

// Update zoom level (triggers node/line re-render in performance mode)
graphInstance.setOptions({
  canvasZoom: 150
});

// Disable user interactions
graphInstance.setOptions({
  disableDragNode: true,
  disableWheelEvent: true
});

Options in Data Transformation

Options are passed to json2Node() and json2Line() converters to apply default styling when creating runtime objects from user input.

Line Data Transformation Pipeline

graph LR
    jsonLine["JsonLine input"]
    json2Line["json2Line(jsonLine, options)
RGLineDataUtils.ts:3"]
    
    validateFrom["Validate from field
must be string (nodeId)
line 4-18"]
    validateTo["Validate to field
must be string (nodeId)
line 4-18"]
    
    handleDeprecated["Handle deprecated:
isShow → hidden
isHide → hidden
line 20-27"]
    
    applyDefaults["Apply option defaults:
lineShape = options.defaultLineShape
line 50"]
    
    setTypes["Set fromType/toType:
Node vs CanvasPoint
line 37-38"]
    
    createRGLine["Return RGLine object
line 31-84"]
    
    jsonLine --> json2Line
    json2Line --> validateFrom
    validateFrom --> validateTo
    validateTo --> handleDeprecated
    handleDeprecated --> applyDefaults
    applyDefaults --> setTypes
    setTypes --> createRGLine

Node Data Transformation Pipeline

graph LR
    jsonNode["JsonNode input"]
    json2Node["json2Node(jsonNode, options, sizeMap)
RGNodeDataUtils.ts:10"]
    
    validateId["Validate id field
must exist
line 11-14"]
    
    handleDeprecated["Handle deprecated:
isShow → hidden
isHide → hidden
line 15-22"]
    
    applyDefaults["Apply option defaults:
nodeShape = options.defaultNodeShape
width = options.defaultNodeWidth
height = options.defaultNodeHeight
line 23-36"]
    
    lookupSize["Lookup cached size:
from nodesSizeMap
line 74-86"]
    
    createRGNode["Return RGNode object
line 27-93"]
    
    jsonNode --> json2Node
    json2Node --> validateId
    validateId --> handleDeprecated
    handleDeprecated --> applyDefaults
    applyDefaults --> lookupSize
    lookupSize --> createRGNode

Option Application in Line Conversion RGLineDataUtils.ts:3-86:

The json2Line() function applies defaults from RGOptions:

Property Default Source Fallback Value Line
lineShape options.defaultLineShape 1 (StandardStraight) 50
type — 'line' 35
fromType — Node or CanvasPoint 37
toType — Node or CanvasPoint 38
showStartArrow — false 56
showEndArrow — true 57

Option Application in Node Conversion RGNodeDataUtils.ts:10-95:

The json2Node() function applies defaults from RGOptions:

Property Default Source Fallback Value Line
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 or width 0 70
el_H nodesSizeMap or height 0 71

Both converters:

  • Handle deprecated isShow/isHide properties, converting to hidden
  • Initialize runtime properties (lot, rgCalcedVisibility, rgShouldRender)
  • Validate required fields and throw errors for invalid data

Option Validation and Error Handling

The configuration system validates options at multiple stages to catch errors and provide helpful messages.

Validation Stages:

1. Update-Time Validation RelationGraphWith3Options1Update.ts:21-46

// Reject plural 'layouts' (common typo)
if (_newOptions['layouts']) {
  throw new Error('Graph options do not support setting layouts properties !');
}

// Auto-fix typo
if (_newOptions.defaultPloyLineRadius) {
  _newOptions.defaultPolyLineRadius = _newOptions.defaultPloyLineRadius;
}

2. Merge-Time Validation RGOptionsDataUtils.ts:194-239

During createDefaultConfig(), unknown option keys are logged but ignored:

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

3. Data Validation in json2Line() and json2Node()

Lines require valid from and to node IDs:

// 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:');
}

Nodes require a unique id:

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

Error Handling Strategy:

Error Type Action Location
Invalid layout name Throw error createLayout() With6Layout.ts:359
Missing node/line ID Throw error Data converters
Unknown option key Log warning, skip createDefaultConfig() RGOptionsDataUtils.ts:200
Common typos Auto-fix _updateOptions() With3Options1Update.ts:29
Invalid property type Throw error Data converters

Platform Integration

Each platform component accepts RGOptions through props and creates a platform-specific data provider that bridges to RelationGraphCore.

Platform Configuration Flow

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
Component"]
    vue3Comp["core4vue3/index.vue
Component"]
    reactComp["RelationGraph.tsx
Component"]
    svelteComp["RelationGraph.svelte
Component"]
    
    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

Platform-Specific Data Provider Creation:

Platform Data Provider Reactivity Mechanism File
Vue 2 RGDataProvider4Vue2 Vue.set() for deep reactivity RGDataProvider4Vue2.ts:12-51
Vue 3 RGDataProvider4Vue3 reactive(), ref() stores RGDataProvider4Vue3.ts:12-49
React RGDataProvider4React setState() callbacks RGDataProvider4React.ts:12-38
Svelte RGDataProvider4Svelte writable() stores RGDataProvider4Svelte.ts:12-44

Example: Vue3 Data Provider Creation RGDataProvider4Vue3.ts:12-49

export const createDataProvider4Vue3 = (options: Rpartial<RGOptionsFull>) => {
  // Create reactive stores
  const optionsRef = reactive(createDefaultConfig(options));
  const shouldRenderNodesRef = ref([]);
  const shouldRenderLinesRef = ref([]);
  const shouldRenderFakeLinesRef = ref([]);
  
  // Create data provider with reactive stores
  const dataProvider = new RGDataProvider();
  dataProvider.options = optionsRef;
  dataProvider.runtimeDATA4ShouldRenderItems.nodes = shouldRenderNodesRef.value;
  dataProvider.runtimeDATA4ShouldRenderItems.lines = shouldRenderLinesRef.value;
  dataProvider.runtimeDATA4ShouldRenderItems.fakeLines = shouldRenderFakeLinesRef.value;
  
  // Set update hook
  dataProvider.updateViewHook = (commits) => {
    // Vue3 reactivity automatically triggers updates
  };
  
  return dataProvider;
};

All platforms ultimately call createDefaultConfig(options) RGOptionsDataUtils.ts:15 to create the full configuration, then wrap it in framework-specific reactivity.

Configuration Categories

The configuration system organizes options into logical categories that control different aspects of graph behavior and appearance.

Primary Configuration Categories

Category Options Count Key Examples Purpose
UI Control ~15 showToolBar, showDebugPanel, fullscreen Control interface visibility
Visual Styling ~20 backgroundColor, defaultNodeColor, defaultLineMarker Define appearance
User Interaction ~12 disableDragNode, selectionMode, wheelEventAction Configure user controls
Canvas Management ~8 canvasSize, canvasOffset, canvasZoom Manage viewport
Layout Control ~1 + sub-options layout object with algorithm-specific properties Control positioning
Performance ~5 performanceMode, showEasyView, enableNodeXYAnimation Optimize rendering
Editing Features ~10 Various editing*Controller objects Enable interactive editing

Critical Configuration Initialization

graph LR
    INSTANCE_ID["instanceId Generation
RGIns-{index}"]
    TEMPLATE_INIT["Template Initialization
newNodeTemplate
newLineTemplate"]
    CONTROLLER_SETUP["Controller Setup
editingController
editingLineController"]
    VIEW_CONFIG["View Configuration
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

The newInstanceOptions() function ensures each graph instance receives a unique identifier and properly initialized configuration objects, preventing cross-instance interference.