react-kggraph

基于 Cytoscape.js 的 React 知识图谱可视化组件库。

特性

• 🚀 基于 Cytoscape.js 强大的图可视化能力
• 📊 支持多种布局算法（cose-bilkent、cise、fcose、storm）
• 🎨 支持节点、边的自定义样式
• 🔍 支持节点搜索、高亮路径分析
• 📦 支持知识图谱展开、节点详情查看
• 📱 响应式设计，支持缩放、拖拽等交互
• ⚙️ 支持 ActionBar 工具栏配置（位置、按钮列表）
• 🖱️ 支持右键菜单（actionCircle）自定义

安装

npm install react-kggraph

依赖

react-kggraph 依赖以下 peerDependencies，请确保已安装：

npm install react react-dom antd @ant-design/icons

使用

基础用法

import { CytoscapeReact } from 'react-kggraph';
import 'react-kggraph/style.css';

const App = () => {
  const data = {
    nodes: [
      { data: { id: '1', label: '刘培' } },
      { data: { id: '2', label: '许冉' } },
    ],
    edges: [
      { data: { source: '1', target: '2', label: '同事' } },
    ],
  };

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <CytoscapeReact data={data} />
    </div>
  );
};

完整示例

import { CytoscapeReact, SearchType, actionList } from 'react-kggraph';
import { MinusCircleOutlined } from '@ant-design/icons';

const App = () => {
  const data = {
    nodes: [
      { data: { id: '1', label: '刘培' } },
      { data: { id: '2', label: '许冉' } },
    ],
    edges: [
      { data: { source: '1', target: '2', label: '同事' } },
    ],
  };

  // 获取完整图谱数据
  const getAllGraphData = async (params) => {
    const response = await fetch('/api/graph', {
      method: 'POST',
      body: JSON.stringify(params),
    });
    return response.json();
  };

  // 节点展开 API
  const stepNextApi = async (params) => {
    const response = await fetch('/api/stepNext', {
      method: 'POST',
      body: JSON.stringify(params),
    });
    return response.json();
  };

  // 知识卡片 API
  const knowledgeCardApi = async (params) => {
    const response = await fetch('/api/knowledgeCard', {
      method: 'POST',
      body: JSON.stringify(params),
    });
    return response.json();
  };

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <CytoscapeReact
        data={data}
        getAllGraphData={getAllGraphData}
        searchType={SearchType.KNOWLEDGE}
        highPathAnalysis={['1', '2']}
        graphInfo={{ kgId: 3, searchNodes: ['刘培', '许冉'] }}
        stepNextApi={stepNextApi}
        knowledgeCardApi={knowledgeCardApi}
        // ActionBar 配置
        actionBar={{
          position: 'top-left',
          actionList: actionList.filter(item => ['queryStatistics', 'layout'].includes(item.key)),
        }}
        // 右键菜单配置
        actionCircle={[
          { ids: 'contract', label: '展收实体' },
          { ids: 'expanded', label: '展收属性' },
          { ids: 'nodeInfo', label: '节点信息' },
          { ids: 'customNew', label: '自定义菜单', onClick: (node) => console.log('自定义', node) },
        ]}
      />
    </div>
  );
};

Props

| 属性 | 类型 | 必填 | 说明 | |------|------|------|------| | data | GraphData \| any[] | ❌ | 图谱数据 | | getAllGraphData | (params?: any) => void | ❌ | 获取完整图谱数据的回调函数 | | searchType | SearchType | ❌ | 搜索类型 | | highPathAnalysis | string[] | ❌ | 高亮路径分析的节点ID数组 | | graphInfo | GraphInfo | ❌ | 图谱配置信息 | | stepNextApi | (params: any) => Promise<any> | ❌ | 下一步API（用于知识图谱展开） | | knowledgeCardApi | (params: any) => Promise<any> | ❌ | 知识卡片API | | colors | GraphColors | ❌ | 颜色配置 | | actionBar | ActionBarConfig | ❌ | ActionBar 工具栏配置 | | actionCircle | ActionCircleItem[] | ❌ | 右键菜单配置 |

ActionBar 配置

ActionBar 工具栏支持自定义位置和按钮列表。

ActionBarConfig

interface ActionBarConfig {
  /** 位置配置 */
  position?: ActionBarPosition;
  /** 按钮列表配置 */
  actionList?: ActionBarItem[];
}

type ActionBarPosition = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | {
  top?: string | number;
  right?: string | number;
  bottom?: string | number;
  left?: string | number;
};

ActionBarItem

interface ActionBarItem {
  key: string;                    // 唯一标识
  title: string;                   // 显示文本
  icon?: React.ReactNode[];        // 图标（支持多个 antd icon）
  onClick?: (params?: any) => void; // 点击事件
}

默认按钮列表

组件内置以下默认按钮：

| key | title | 说明 | |-----|-------|------| | queryStatistics | 查询统计 | 统计面板 | | layout | 布局 | 布局切换 | | graphDisplaySettings | 图显示设置 | 图形显示配置 | | analysis | 分析 | 分析功能 | | select | 选择 | 选择功能 | | downloadData | 下载数据 | 导出数据 | | hideAttributes | 隐藏属性 | 隐藏节点属性 | | textPosition | 文字位置 | 文字位置调整 | | clearCanvas | 清空画布 | 清空画布 | | nodeZoom | 节点缩放 | 节点缩放控制 | | canvasZoom | 画布缩放 | 画布缩放控制 |

ActionBar 示例

// 方式1：使用预定义 actionList
import { actionList } from 'react-kggraph';
import { MinusCircleOutlined } from '@ant-design/icons';

<CytoscapeReact
  actionBar={{
    position: 'top-left',
    actionList: actionList.filter(item => ['queryStatistics', 'layout'].includes(item.key)),
  }}
/>

// 方式2：自定义按钮
<CytoscapeReact
  actionBar={{
    position: 'bottom-right',
    actionList: [
      { key: 'customBtn', title: '自定义按钮', icon: [<MinusCircleOutlined key="icon" />], onClick: () => console.log('点击') },
    ],
  }}
/>

右键菜单配置（actionCircle）

右键菜单支持过滤、追加自定义菜单项。

ActionCircleItem

interface ActionCircleItem {
  ids: string;                    // 唯一标识
  label: string;                  // 显示文本
  onClick?: (node: any) => void;  // 点击事件回调
}

默认菜单项

| ids | label | 说明 | |-----|-------|------| | contract | 展收实体 | 收缩实体节点 | | expanded | 展收属性 | 展开节点属性 | | nodeInfo | 节点信息 | 查看节点详情 | | knowledgeCard | 知识卡片 | 查看知识卡片 | | selRelate | 选中关联 | 高亮关联节点 | | pathAnalysis | 路径分析 | 路径分析功能 |

actionCircle 示例

// 方式1：筛选默认菜单
<CytoscapeReact
  actionCircle={[
    { ids: 'contract', label: '展收实体' },
    { ids: 'expanded', label: '展收属性' },
    { ids: 'nodeInfo', label: '节点信息' },
  ]}
/>

// 方式2：覆盖默认 action
<CytoscapeReact
  actionCircle={[
    { ids: 'nodeInfo', label: '节点信息', onClick: (node) => console.log('自定义', node) },
  ]}
/>

// 方式3：追加自定义菜单项
<CytoscapeReact
  actionCircle={[
    { ids: 'contract', label: '展收实体' },
    { ids: 'customNew', label: '自定义菜单', onClick: (node) => console.log('新增功能', node) },
  ]}
/>

类型定义

GraphData

interface GraphData {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

interface GraphNode {
  data: {
    id: string;
    label: string;
    type?: string;
    properties?: Record<string, any>;
  };
}

interface GraphEdge {
  data: {
    id?: string;
    source: string;
    target: string;
    label?: string;
    type?: string;
    properties?: Record<string, any>;
  };
}

GraphInfo

interface GraphInfo {
  kgId: number | string;
  searchNodes?: string[];
}

GraphColors（颜色配置）

interface GraphColors {
  /** 节点标签文字颜色，默认 #000 */
  nodeLabelColor?: string;
  /** 节点标签文字大小，默认 18 */
  nodeLabelFontSize?: number;
  /** 边标签文字颜色，默认 #666 */
  edgeLabelColor?: string;
  /** 边标签文字大小，默认 18 */
  edgeLabelFontSize?: number;
  /** URI类型节点背景色，默认 #f7de63 */
  uriNodeColor?: string;
  /** 普通节点背景色，默认 #1890FF */
  normalNodeColor?: string;
  /** 节点边框悬停颜色，默认 #0d6ac2 */
  nodeBorderHoverColor?: string;
  /** 边默认颜色，默认 #a29e9e */
  edgeDefaultColor?: string;
  /** 边悬停颜色，默认 #1890ff */
  edgeHoverColor?: string;
  /** 路径高亮颜色，默认 #145AFD */
  pathHighlightColor?: string;
  /** 路径节点颜色，默认 #145AFD */
  pathNodeColor?: string;
}

颜色配置示例

<CytoscapeReact
  data={data}
  colors={{
    nodeLabelColor: '#333',
    edgeLabelColor: '#999',
    normalNodeColor: '#52c41a',
    uriNodeColor: '#faad14',
    edgeDefaultColor: '#d9d9d9',
    pathHighlightColor: '#f5222d',
  }}
/>

图谱布局

组件支持多种布局算法：

| 布局名称 | 说明 | |---------|------| | cose-bilkent | 力导向布局（默认） | | cise | 聚类布局 | | fcose | 快速力导向布局 | | storm | 风暴布局 |

License

MIT