@mxmweb/nodegraph

基于 @antv/g6 的可视化节点图组件库，提供灵活的配置和扩展能力

✨ 核心特性

• ✅ 丰富的交互行为：支持画布拖拽、缩放、滚轮、元素选择、聚焦、悬停等操作
• ✅ 可扩展的插件系统：内置背景、网格、图例、工具栏、提示框、全屏等插件
• ✅ 灵活的数据变换：支持多种数据格式转换，适配不同场景需求
• ✅ 预设配置：提供 minimal、standard、advanced、full、preview 等预设配置
• ✅ TypeScript 支持：完整的类型定义，提供良好的开发体验

📦 安装

# 使用 pnpm
pnpm add @mxmweb/nodegraph

# 使用 npm
npm install @mxmweb/nodegraph

# 使用 yarn
yarn add @mxmweb/nodegraph

必需依赖

本库需要以下 peerDependencies：

pnpm add @mxmweb/zui@^1.* @antv/g6@^5.0.50 react@>=18 react-dom@>=18

🚀 快速开始

基础用法

import React from 'react';
import { NodeGraph } from '@mxmweb/nodegraph';
import '@mxmweb/nodegraph/style.css';

function App() {
  const data = {
    nodes: [
      { id: '1', data: { label: 'Node 1' } },
      { id: '2', data: { label: 'Node 2' } }
    ],
    edges: [
      { id: 'e1', source: '1', target: '2' }
    ]
  };

  return (
    <NodeGraph
      data={data}
      width={800}
      height={600}
      behaviors="standard"
      plugins="standard"
      onReady={(graph) => {
        console.log('Graph ready:', graph);
      }}
    />
  );
}

export default App;

使用预设配置

import React from 'react';
import { NodeGraph } from '@mxmweb/nodegraph';
import '@mxmweb/nodegraph/style.css';

function App() {
  return (
    <NodeGraph
      data={data}
      behaviors="full"  // 使用完整的交互行为
      plugins="full"    // 使用所有可用插件
    />
  );
}

🔗 链接

• NPM: https://www.npmjs.com/package/@mxmweb/nodegraph
• GitHub: https://github.com/your-org/nodegraph

📚 API 文档

📖 完整 API 文档请查看：doc_assets/接口/

• 接口文档: NodeGraph API、KnowledgeGraphPreview API
• 更新说明: CHANGELOG
• 演示说明: 演示文档

核心组件（Core Components）

NodeGraph

核心节点图组件，提供基础的图表渲染和交互能力。

interface NodeGraphProps {
  data: any;
  behaviors?: BehaviorOptions | 'minimal' | 'standard' | 'advanced' | 'full' | 'preview';
  plugins?: PluginOptions | PluginPreset;
  width?: number;
  height?: number;
  layout?: LayoutOptions | LayoutPreset;
  theme?: any;
  onReady?: (graph: Graph) => void;
  onDestroy?: (graph: Graph) => void;
}

Props 说明：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | data | any | 必填 | 图数据，包含 nodes 和 edges | | behaviors | BehaviorOptions | preset | 'standard' | 交互行为配置 | | plugins | PluginOptions | preset | 'standard' | 插件配置 | | width | number | 容器宽度 | 画布宽度（像素） | | height | number | 容器高度 | 画布高度（像素） | | layout | LayoutOptions | preset | 'force' | 布局配置 | | theme | any | - | 主题配置 | | onReady | (graph) => void | - | 图表就绪回调 | | onDestroy | (graph) => void | - | 图表销毁回调 |

registerPreviewViewer

注册预览查看器功能。

registerPreviewViewer(config);

扩展组件（Adopters）

KnowledgeGraphPreview

知识图谱预览组件，基于 NodeGraph 构建，专门用于知识图谱可视化。

interface KnowledgeGraphPreviewProps {
  data: any;
  title?: string;
  subtitle?: string;
  backgroundColor?: string;
  showGrid?: boolean;
  showLegend?: boolean;
  showTooltip?: boolean;
  showFullscreen?: boolean;
  showMinimap?: boolean;
  layout?: any;
  customPlugins?: Partial<PluginOptions>;
  onReady?: (graph: any) => void;
  onDestroy?: (graph: any) => void;
}

使用示例：

import { KnowledgeGraphPreview } from '@mxmweb/nodegraph';
import '@mxmweb/nodegraph/style.css';

function KnowledgeGraph() {
  const knowledgeData = {
    nodeList: [
      { id: '1', name: '概念1' },
      { id: '2', name: '概念2' }
    ],
    edgeList: [
      { source: '1', target: '2', label: '关系' }
    ]
  };

  return (
    <KnowledgeGraphPreview
      data={knowledgeData}
      title="知识图谱"
      showLegend={true}
      showTooltip={true}
    />
  );
}

配置模块

behaviors（行为配置）

定义图表的交互行为。

import { createPresetBehaviors } from '@mxmweb/nodegraph';

// 使用预设
const behaviors = createPresetBehaviors('full');

// 或自定义配置
const customBehaviors = {
  dragCanvas: true,
  zoomCanvas: true,
  clickSelect: true,
  // ... 更多配置
};

可用行为：

• dragCanvas - 画布拖拽
• zoomCanvas - 画布缩放
• scrollCanvas - 画布滚动
• clickSelect - 点击选择
• dragElement - 元素拖拽
• focusElement - 元素聚焦
• hoverActivate - 悬停激活

plugins（插件配置）

定义图表的插件功能。

import { createPresetPlugins } from '@mxmweb/nodegraph';

// 使用预设
const plugins = createPresetPlugins('full');

// 或自定义配置
const customPlugins = {
  background: { type: 'color', color: '#fff' },
  grid: true,
  legend: true,
  toolbar: true,
  tooltip: true,
  // ... 更多配置
};

可用插件：

• background - 背景插件
• grid - 网格插件
• legend - 图例插件
• title - 标题插件
• toolbar - 工具栏插件
• tooltip - 提示框插件
• fullscreen - 全屏插件
• minimap - 缩略图插件

预设配置

Behaviors 预设

• minimal - 最小配置，仅基础交互
• standard - 标准配置，包含常用交互
• advanced - 高级配置，包含更多交互选项
• full - 完整配置，包含所有交互
• preview - 预览模式配置

Plugins 预设

• minimal - 最小插件配置
• standard - 标准插件配置
• advanced - 高级插件配置
• full - 完整插件配置

🛠️ 技术栈

• @antv/g6 ^5.0.50 - 图可视化引擎
• React >=18 <20 - 前端框架
• @mxmweb/zui ^1.* - UI 组件库
• TypeScript - 类型支持

📁 项目结构

src/
├── lib_enter.ts              # 库入口，导出所有公共 API
├── style.css                 # 样式文件
├── core/                     # 核心组件
│   ├── index.tsx             # NodeGraph 核心组件
│   ├── behaviors/            # 行为配置模块
│   │   ├── index.ts
│   │   ├── generator.ts
│   │   └── types.ts
│   ├── plugins/              # 插件配置模块
│   │   ├── index.ts
│   │   ├── generator.ts
│   │   └── types.ts
│   ├── layouts/              # 布局模块
│   │   └── types.ts
│   ├── dataTransform.ts      # 数据转换
│   └── register.ts           # 注册功能
├── adopters/                 # 业务扩展组件
│   └── KnowledgeGraphPreview/
│       └── index.tsx
└── examples/                 # 演示实例
    ├── Coregraph/
    └── KnowledgePreview/

🎯 使用场景

• 知识图谱可视化
• 关系网络展示
• 数据流程图
• 组织结构图
• 依赖关系图

📝 示例

查看 src/examples/ 目录获取更多完整示例：

• Coregraph - 核心组件基础用法
• KnowledgePreview - 知识图谱预览完整示例

🤝 贡献

欢迎提交 Issue 和 Pull Request。

📄 许可证

MIT License

👥 作者

• hanfeng_Zhang

⭐ 如果这个项目对你有帮助，请给它一个 Star！