npm package: @mxmweb/nodegraph
Description: > 基于 @antv/g6 的可视化节点图组件库，提供灵活的配置和扩展能力
Author: hanfeng_Zhang
Latest version: 1.1.7

# @mxmweb/nodegraph

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

[![npm version](https://img.shields.io/npm/v/@mxmweb/nodegraph.svg)](https://www.npmjs.com/package/@mxmweb/nodegraph)
[![npm downloads](https://img.shields.io/npm/dm/@mxmweb/nodegraph.svg)](https://www.npmjs.com/package/@mxmweb/nodegraph)
[![License](https://img.shields.io/npm/l/@mxmweb/nodegraph.svg)](https://github.com/your-org/nodegraph/blob/main/LICENSE)

## ✨ 核心特性

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

## 📦 安装

```bash
# 使用 pnpm
pnpm add @mxmweb/nodegraph

# 使用 npm
npm install @mxmweb/nodegraph

# 使用 yarn
yarn add @mxmweb/nodegraph
```

### 必需依赖

本库需要以下 peerDependencies：

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

## 🚀 快速开始

### 基础用法

```tsx
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;
```

### 使用预设配置

```tsx
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/接口/](./doc_assets/接口/)

- **接口文档**: [NodeGraph API](./doc_assets/接口/NodeGraph.md)、[KnowledgeGraphPreview API](./doc_assets/接口/KnowledgeGraphPreview.md)
- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
- **演示说明**: [演示文档](./doc_assets/演示/index.md)

### 核心组件（Core Components）

#### NodeGraph

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

```typescript
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

注册预览查看器功能。

```typescript
registerPreviewViewer(config);
```

### 扩展组件（Adopters）

#### KnowledgeGraphPreview

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

```tsx
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;
}
```

**使用示例**：

```tsx
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（行为配置）

定义图表的交互行为。

```tsx
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（插件配置）

定义图表的插件功能。

```tsx
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** - 类型支持

## 📁 项目结构

```text
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！