Relation Graph

RelationGraphInstance API

RelationGraphInstance is the core runtime object in relation-graph.
It provides data CRUD, viewport control, layout execution, interaction control, import/export, and image-generation helpers.

1. How to Get the Instance

A. Via `onReady` (recommended)

let graphInstance: RelationGraphInstance | undefined;

const onReady = (instance: RelationGraphInstance) => {
  graphInstance = instance;
};

B. Via component ref

const graphInstance = graphRef.value?.getInstance?.();

2. API Capability Map

Public APIs can be grouped by responsibility:

Base utilities: generateNewUUID, enableDebugLog, addEventHandler
Coordinate/view conversion: getViewXyByEvent, getCanvasXyByViewXy, getViewXyByCanvasXy
Data getters: getNodeById, getLineById, getNodes, getLines, getLinks
Graph analysis: getNodeRelatedNodes, getNetworkNodesByNode, getNodesRectBox
CRUD: addNodes, addLines, updateNode, updateLine, removeNodeById
Interaction state: setCheckedNode, clearChecked, expandNode, collapseNode
Zoom/canvas: zoom, setZoom, zoomToFit, moveToCenter
Layout control: doLayout, createLayout, startAutoLayout, stopAutoLayout
Editing control: setEditingNodes, setEditingLine, startMoveLineVertex
Import/export: setJsonData, appendJsonData, getGraphJsonData, clearGraph
Image workflow: prepareForImageGeneration, restoreAfterImageGeneration

3. High-Value Methods Quick Reference

Scenario	Methods
Initialize full graph	`setJsonData(jsonData)`
Append data	`appendJsonData(jsonData, isRelayout?)`
Export current graph	`getGraphJsonData()`
Add nodes/lines	`addNodes(nodes)`, `addLines(lines)`
Patch style/business data	`updateNode(nodeId, patch)`, `updateLine(lineId, patch)`
Find entities	`getNodeById`, `getLineById`, `getLinkByLineId`
Fit viewport	`moveToCenter(nodes?)`, `zoomToFit(nodes?)`
Trigger layout	`doLayout(customRootNode?)`, `createLayout(options)`
Fullscreen	`fullscreen(newValue?)`
Screenshot lifecycle	`prepareForImageGeneration()`, `restoreAfterImageGeneration()`

4. Common Usage Flows

A. Initial load + fit

await graphInstance.setJsonData(jsonData);
graphInstance.moveToCenter();
graphInstance.zoomToFit();

B. Dynamic add node + line

const nodeId = graphInstance.generateNewNodeId(8);
graphInstance.addNodes([{ id: nodeId, text: "New Node" }]);
graphInstance.addLines([{ from: "a", to: nodeId, text: "new link" }]);
graphInstance.moveToCenter();

C. Patch node/line state

graphInstance.updateNode("node-1", { color: "#0ea5e9", borderWidth: 2 });
graphInstance.updateNodeData("node-1", { owner: "team-a", score: 98 });

graphInstance.updateLine("line-1", { color: "#ef4444", lineWidth: 2 });
graphInstance.updateLineData("line-1", { status: "warning" });

5. Event-Driven Integration Notes

Validate line creation in beforeCreateLine by returning false.
For line endpoint reconnection, you typically finalize in onLineBeCreated with addLines(...).
Use beforeZoomStart / beforeScrollStart as policy gates for interaction modes.

6. Coordinate Conversion (Frequently Used)

For menus, drag-create, and context interactions:

getViewXyByEvent(e): event -> viewport coordinates
getCanvasXyByViewXy({ x, y }): viewport -> canvas coordinates
getViewXyByCanvasXy({ x, y }): canvas -> viewport coordinates

7. Layout Control Recommendations

Static graph: one-time doLayout().
Dynamic force graph: control iterations with startAutoLayout() / stopAutoLayout().
Partial/custom layout: use createLayout(layoutOptions, isMainLayout?).

8. Import/Export and Debug

Export JSON: getGraphJsonData(), printGraphJsonData()
Debug switch: enableDebugLog(true/false)
Reset graph: clearGraph() then setJsonData(...)

9. Practical Advice

Keep a single instance reference in app scope.
Use public instance APIs to mutate graph state; avoid touching runtime internals.
Throttle expensive logic in high-frequency callbacks.
Keep business constraints in events, and action execution in instance APIs.