Relation Graph

在 React 中使用

本页为 relation-graph 的 React 使用指南，内容依据 ai-prompts/relation-graph-guide.md 整理。

1. 安装

npm install --save @relation-graph/react

旧包名 relation-graph-react 仍可用，但推荐使用 @relation-graph/react。

2. 需要用到的核心组件

RGProvider：提供图谱上下文（实例 + 响应式状态）。
RelationGraph：渲染图谱视图。
RGHooks：在 React 组件中获取图谱实例和状态。

3. 最小可用 React 示例

import React, { useEffect } from 'react';
import { RGProvider, RelationGraph, RGHooks } from '@relation-graph/react';
import type { JsonNode, JsonLine, RGOptions } from '@relation-graph/react';

const GraphView: React.FC = () => {
  const graphInstance = RGHooks.useGraphInstance();

  const graphOptions: RGOptions = {
    showToolBar: false,
    wheelEventAction: 'scroll',
    dragEventAction: 'move',
    layout: {
      layoutName: 'tree',
      from: 'left',
      treeNodeGapH: 150,
      treeNodeGapV: 10
    }
  };

  const initializeGraph = async () => {
    const nodes: JsonNode[] = [
      { id: '1', text: 'Root' },
      { id: '2', text: 'React App' },
      { id: '3', text: 'Graph Engine' },
      { id: '4', text: 'API Layer' }
    ];
    const lines: JsonLine[] = [
      { from: '1', to: '2', text: 'uses' },
      { from: '1', to: '3', text: 'drives' },
      { from: '2', to: '4', text: 'calls' }
    ];

    graphInstance.clearGraph();
    graphInstance.addNodes(nodes);
    graphInstance.addLines(lines);

    // 如果节点未预设 width/height，建议等待节点尺寸测量完成后再布局。
    setTimeout(() => {
      const layouter = graphInstance.createLayout({
        layoutName: 'tree',
        from: 'left',
        treeNodeGapH: 150,
        treeNodeGapV: 10
      });
      const allNodes = graphInstance.getNodes();
      const rootNode = graphInstance.getNodeById('1');
      if (rootNode) {
        layouter.placeNodes(allNodes, rootNode);
      }
      graphInstance.moveToCenter();
      graphInstance.zoomToFit();
    }, 300);
  };

  useEffect(() => {
    initializeGraph();
  }, []);

  return (
    <div style={{ width: '100vw', height: '100vh', backgroundColor: '#ffffff' }}>
      <RelationGraph options={graphOptions} />
    </div>
  );
};

const MyGraphPage: React.FC = () => {
  return (
    <RGProvider>
      <GraphView />
    </RGProvider>
  );
};

export default MyGraphPage;

4. 向图谱提供数据的三种方式

在 React 中常用三种数据接入方式：

addNodes + addLines + 手动布局（适合动态、精细更新）。
setJsonData 一次性设置（适合初次完整加载）。
initialData 属性初始化（适合初始化/SSR 场景）。

4.1 使用 `setJsonData` 一次性设置

const initializeGraph = () => {
  const nodes: JsonNode[] = [
    { id: '1', text: 'Root' },
    { id: '2', text: 'A' },
    { id: '3', text: 'B' }
  ];
  const lines: JsonLine[] = [
    { from: '1', to: '2' },
    { from: '1', to: '3' }
  ];

  graphInstance.setJsonData({
    rootId: '1',
    nodes,
    lines
  });
};

setJsonData 内部会完成清空、添加、布局、居中和缩放，适合快速展示完整图谱。

4.2 通过 `initialData` 初始化

<RelationGraph
  options={graphOptions}
  initialData={{
    rootId: '1',
    nodes,
    lines
  }}
/>

5. 注册交互事件

import type { RGNode, RGLine, RGLink, RGUserEvent } from '@relation-graph/react';

const onNodeClick = (nodeObject: RGNode, event: RGUserEvent) => {
  console.log('node click:', nodeObject.id, event);
};

const onLineClick = (lineObject: RGLine, linkObject: RGLink, event: RGUserEvent) => {
  console.log('line click:', lineObject.from, lineObject.to, linkObject, event);
};

<RelationGraph
  options={graphOptions}
  onNodeClick={onNodeClick}
  onLineClick={onLineClick}
/>

6. 使用 `RGHooks` 获取图谱状态

RGHooks 提供图谱运行时的响应式状态：

const graphInstance = RGHooks.useGraphInstance();
const creatingLine = RGHooks.useCreatingLine();
const creatingNode = RGHooks.useCreatingNode();
const editingNodes = RGHooks.useEditingNodes();
const editingLine = RGHooks.useEditingLine();
const connectingNode = RGHooks.useConnectingNode();
const viewInformation = RGHooks.useViewInformation();
const selectionView = RGHooks.useSelectionView();
const checkedItem = RGHooks.useCheckedItem();

这些状态可直接驱动你的工具栏、属性面板、编辑器侧栏等 UI。

7. 实践建议

<RelationGraph> 的尺寸由其父容器尺寸决定。
options 更偏向“初始配置”；运行时修改建议使用 graphInstance.updateOptions(...)。
如果 <RGProvider> 不卸载而 <RelationGraph> 重挂载，加载新数据前建议 graphInstance.clearGraph()。
动态编辑场景优先使用增量 API（addNodes/addLines/update/remove），避免频繁 setJsonData 带来的视图抖动。