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

Events (RGListeners)

relation-graph exposes a full event system through RGListeners for lifecycle hooks, node/line interactions, canvas behaviors, and editing workflows.

1. How to Register Events

A. Bind on <RelationGraph> props/events

<template>
  <RelationGraph
    :options="graphOptions"
    @onReady="onReady"
    @onNodeClick="onNodeClick"
    @onLineClick="onLineClick"
    @onContextmenu="onContextmenu"
  />
</template>

B. Use addEventListener in Web Components

<relation-graph id="my-graph"></relation-graph>
<script>
  const el = document.getElementById('my-graph');
  el.addEventListener('onNodeClick', (event) => {
    const [node, userEvent] = event.detail;
    console.log(node, userEvent);
  });
</script>

2. Event Categories

  • Lifecycle: onReady, onViewResize, onForceLayoutFinish
  • Node/line interaction: onNodeClick, onLineClick, onNodeExpand, onNodeCollapse
  • Drag flow: onNodeDragStart, onNodeDragging, onNodeDragEnd, onCanvasDragStart, onCanvasDragging, onCanvasDragEnd
  • Canvas actions: onCanvasClick, onCanvasSelectionEnd, onContextmenu, onFullscreen
  • Zoom/scroll: beforeZoomStart, onZoomEnd, beforeScrollStart
  • Editing flow: onResizeStart, beforeNodeResize, onResizeEnd, onLineVertexDropped, beforeCreateLine, onLineBeCreated
  • Data ingress: beforeAddNodes, beforeAddLines
  • Keyboard: onKeyboardDown, onKeyboardUp

3. Key Events and Signatures

onReady

(graphInstance: RelationGraphInstance) => void

Use it to store the instance and call APIs such as setJsonData, addNodes, zoomToFit, etc.

onNodeClick / onLineClick

(node: RGNode, e: RGUserEvent) => boolean | void | Promise<boolean | void>
(line: RGLine, link: RGLink, e: RGUserEvent) => boolean | void | Promise<boolean | void>

Return boolean (or Promise<boolean>) when you need to influence follow-up default behavior.

onContextmenu

(e: RGUserEvent, objectType: 'canvas' | 'node' | 'line', object, eventPositionOnCanvas, eventPositionOnView) => void

A single entry for custom context menus on canvas, nodes, and lines.

beforeZoomStart / beforeScrollStart

beforeZoomStart: () => void | false
beforeScrollStart: (buffX: number, buffY: number, e: Event) => true | undefined | void
  • Return false in beforeZoomStart to block zoom.
  • Return true in beforeScrollStart to block scroll.

beforeCreateLine / onLineBeCreated

beforeCreateLine: (lineInfo) => void | false
onLineBeCreated: (lineInfo) => void

Use these for validation and persistence during line creation/reconnect flows. When reconnecting line endpoints, add the new line back via graphInstance.addLines(...) in onLineBeCreated.

4. Common Event Combination

let graphInstance: RelationGraphInstance | undefined;

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

const beforeCreateLine = ({ fromNode, toNode }) => {
  if (fromNode.id === toNode.id) return false; // block self-loop
};

const onLineBeCreated = ({ lineJson }) => {
  if (!graphInstance) return;
  graphInstance.addLines([lineJson]);
};

5. Relationship with RGOptions

Several options directly affect interaction/event behavior:

  • wheelEventAction: zoom, scroll, or none for wheel events
  • dragEventAction: move canvas, selection, or none for drag events
  • disableNodePointEvent: disable node interaction events
  • disableLinePointEvent: disable line interaction events

6. Practical Tips

  • Always capture instance in onReady before complex event logic.
  • Use blocking events as policy gates (permissions, validation, constraints).
  • Avoid heavy computation in high-frequency callbacks.
  • Standardize context-menu branching with objectType.

7. Next Reading