react-kggraph 0.0.37 → 0.0.39

package/README.md

@@ -5,13 +5,18 @@
 ## 特性
 
 - 🚀 基于 Cytoscape.js 强大的图可视化能力
-- 📊 支持多种布局算法（cose-bilkent、cise、fcose、storm）
-- 🎨 支持节点、边的自定义样式
-- 🔍 支持节点搜索、高亮路径分析
-- 📦 支持知识图谱展开、节点详情查看
-- 📱 响应式设计，支持缩放、拖拽等交互
-- ⚙️ 支持 ActionBar 工具栏配置（位置、按钮列表）
-- 🖱️ 支持右键菜单（actionCircle）自定义
+- 📊 支持多种布局算法（cose-bilkent、cise、fcose、cose、grid、circle、breadthfirst、concentric）
+- 🎨 支持节点、边的自定义样式，节点/边 Drawer 编辑
+- 🔍 支持节点搜索、框选/点选模式、全选/反选
+- 📦 支持知识图谱展开/收起（concentric 环形动画 + 淡入淡出，空白区域自适应）
+- 📋 支持数据导出（JSON / Excel / PNG / JPG）
+- 📱 响应式设计，支持画布缩放、节点缩放、拖拽等交互
+- ⚙️ 支持 ActionBar 工具栏配置（位置、按钮列表、折叠展开）
+- 🖱️ 支持右键径向菜单（actionCircle）自定义
+- 🗺️ 路径分析：支持多节点间 A* 最短路径计算
+- 🔗 连接分析：BFS 遍历 N 度关联节点
+- 📊 查询统计面板：实体/关系类型分布及筛选
+- 📝 知识卡片：节点详情抽屉展示
 
 ## 安装
 
@@ -110,14 +115,14 @@ const App = () => {
         knowledgeCardApi={knowledgeCardApi}
         // ActionBar 配置
         actionBar={{
-          position: 'top-left',
+          position: 'left',
           actionList: actionList.filter(item => ['queryStatistics', 'layout'].includes(item.key)),
         }}
         // 右键菜单配置
         actionCircle={[
           { ids: 'contract', label: '展收实体' },
           { ids: 'expanded', label: '展收属性' },
-          { ids: 'nodeInfo', label: '节点信息' },
+          { ids: 'nodeInfo', label: '节点样式' },
           { ids: 'customNew', label: '自定义菜单', onClick: (node) => console.log('自定义', node) },
         ]}
       />
@@ -128,98 +133,119 @@ const App = () => {
 
 ## 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[]` | ❌ | 右键菜单配置 |
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| data | `GraphData \| any[]` | ❌ | — | 图谱数据 |
+| getAllGraphData | `(params?: any) => Promise<any>` | ❌ | — | 获取完整图谱数据的回调 |
+| searchType | `SearchType` | ❌ | — | 搜索类型 |
+| highPathAnalysis | `string[]` | ❌ | `[]` | 高亮路径分析的节点ID数组 |
+| graphInfo | `GraphInfo` | ❌ | — | 图谱配置信息（kgId + searchNodes） |
+| stepNextApi | `(params: any) => Promise<any>` | ❌ | — | 节点展开/收起 API |
+| knowledgeCardApi | `(params: any) => Promise<any>` | ❌ | — | 知识卡片 API |
+| colors | `GraphColors` | ❌ | — | 颜色配置（与默认值合并） |
+| actionBar | `boolean \| ActionBarConfig` | ❌ | — | 工具栏配置（true=默认，false=隐藏） |
+| actionCircle | `ActionCircleItem[]` | ❌ | — | 右键菜单配置（覆盖/追加默认项） |
+| queryStatisticsConfig | `boolean \| {label, key}[]` | ❌ | `[{label:'实体',key:'entity'},{label:'关系',key:'relation'}]` | 统计面板配置 |
+| noDataDesc | `string` | ❌ | `'暂无数据'` | 无数据时的描述文字 |
+| className | `string` | ❌ | — | 外层容器自定义 class |
+
+### SearchType
+
+```typescript
+enum SearchType {
+  KNOWLEDGE = 'knowledge',   // 知识图谱
+  RELATION = 'relation',     // 关系图谱
+  ATTRIBUTE = 'attribute',   // 属性图谱
+  TIMELINE = 'timeline',     // 时间线图谱
+}
+```
 
 ## ActionBar 配置
 
-ActionBar 工具栏支持自定义位置和按钮列表。
+ActionBar 工具栏支持自定义位置、按钮列表和折叠展开。
 
 ### ActionBarConfig
 
 ```typescript
 interface ActionBarConfig {
-  /** 位置配置 */
-  position?: ActionBarPosition;
-  /** 按钮列表配置 */
+  /** 位置预设 */
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  /** 位置微调偏移 */
+  positionDetail?: {
+    top?: string | number;
+    right?: string | number;
+    bottom?: string | number;
+    left?: string | number;
+  };
+  /** 按钮列表 */
   actionList?: ActionBarItem[];
+  /** 是否默认展开 */
+  isExpand?: boolean;
 }
-
-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
 
 ```typescript
 interface ActionBarItem {
-  key: string;                    // 唯一标识
-  title: string;                   // 显示文本
-  icon?: React.ReactNode[];        // 图标（支持多个 antd icon）
-  onClick?: (params?: any) => void; // 点击事件
+  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 | 画布缩放 | 画布缩放控制 |
+| queryStatistics | 查询统计 | 实体/关系统计面板，支持类型筛选 |
+| layout | 布局 | 8 种布局切换（下拉菜单） |
+| graphDisplaySettings | 图设置 | 节点/连线样式设置 Drawer |
+| analysis | 分析 | 查询节点 / 连接分析 / 路径分析 |
+| select | 选择 | 全选 / 反选 / 点选模式 / 框选模式 |
+| downloadData | 下载数据 | JSON / Excel / JPG / PNG 导出 |
+| hideAttributes | 隐藏属性 | 切换 typed-literal 节点显隐 |
+| textPosition | 文字位置 | 居中 / 上 / 下 / 左 / 右 |
+| clearCanvas | 清空画布 | 清除所有元素 |
+| nodeZoom | 节点缩放 | 放大/缩小节点（0.1x - 5x） |
+| canvasZoom | 画布缩放 | 放大/缩小画布（0.1x - 3x） |
+| tablelist | 查看列表 | 节点/边数据表格列表 |
 
 ### ActionBar 示例
 
 ```tsx
-// 方式1：使用预定义 actionList
+// 方式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)),
+    position: 'left',
+    isExpand: true,
+    actionList: actionList.filter(item => ['queryStatistics', 'layout', 'analysis'].includes(item.key)),
   }}
 />
 
 // 方式2：自定义按钮
+import { MinusCircleOutlined } from '@ant-design/icons';
+
 <CytoscapeReact
   actionBar={{
-    position: 'bottom-right',
+    position: 'right',
+    positionDetail: { top: '20px' },
     actionList: [
-      { key: 'customBtn', title: '自定义按钮', icon: [<MinusCircleOutlined key="icon" />], onClick: () => console.log('点击') },
+      { key: 'customBtn', title: '自定义', icon: [<MinusCircleOutlined key="icon" />], onClick: () => console.log('点击') },
     ],
   }}
 />
+
+// 方式3：隐藏 ActionBar
+<CytoscapeReact data={data} actionBar={false} />
 ```
 
 ## 右键菜单配置（actionCircle）
 
-右键菜单支持过滤、追加自定义菜单项。
+右键径向菜单，传入的项会与默认项按 ids 合并（匹配则覆盖 onClick，不存在则追加）。
 
 ### ActionCircleItem
 
@@ -227,7 +253,7 @@ import { MinusCircleOutlined } from '@ant-design/icons';
 interface ActionCircleItem {
   ids: string;                    // 唯一标识
   label: string;                  // 显示文本
-  onClick?: (node: any) => void;  // 点击事件回调
+  onClick?: (node: any) => void;  // 点击事件（覆盖默认行为）
 }
 ```
 
@@ -235,12 +261,12 @@ interface ActionCircleItem {
 
 | ids | label | 说明 |
 |-----|-------|------|
-| contract | 展收实体 | 收缩实体节点 |
-| expanded | 展收属性 | 展开节点属性 |
-| nodeInfo | 节点信息 | 查看节点详情 |
-| knowledgeCard | 知识卡片 | 查看知识卡片 |
-| selRelate | 选中关联 | 高亮关联节点 |
-| pathAnalysis | 路径分析 | 路径分析功能 |
+| contract | 展收实体 | 展开/收起 URI 类型关联节点（调用 stepNextApi） |
+| expanded | 展收属性 | 展开/收起 typed-literal 类型属性节点（调用 stepNextApi） |
+| nodeInfo | 节点样式 | 打开节点样式编辑 Drawer（名称/形状/大小/边框/字体） |
+| knowledgeCard | 知识卡片 | 调用 knowledgeCardApi 打开知识卡片 Drawer |
+| selRelate | 选中关联 | 高亮直接关联的节点和边 |
+| pathAnalysis | 路径分析 | 设置路径起点，打开路径分析面板 |
 
 ### actionCircle 示例
 
@@ -250,14 +276,14 @@ interface ActionCircleItem {
   actionCircle={[
     { ids: 'contract', label: '展收实体' },
     { ids: 'expanded', label: '展收属性' },
-    { ids: 'nodeInfo', label: '节点信息' },
+    { ids: 'nodeInfo', label: '节点样式' },
   ]}
 />
 
-// 方式2：覆盖默认 action
+// 方式2：覆盖默认 onClick
 <CytoscapeReact
   actionCircle={[
-    { ids: 'nodeInfo', label: '节点信息', onClick: (node) => console.log('自定义', node) },
+    { ids: 'nodeInfo', label: '节点信息', onClick: (node) => console.log('自定义处理', node) },
   ]}
 />
 
@@ -265,7 +291,7 @@ interface ActionCircleItem {
 <CytoscapeReact
   actionCircle={[
     { ids: 'contract', label: '展收实体' },
-    { ids: 'customNew', label: '自定义菜单', onClick: (node) => console.log('新增功能', node) },
+    { ids: 'customNew', label: '自定义菜单', onClick: (node) => alert(node.id()) },
   ]}
 />
 ```
@@ -305,39 +331,26 @@ interface GraphEdge {
 
 ```typescript
 interface GraphInfo {
-  kgId: number | string;
-  searchNodes?: string[];
+  kgId: number | string;     // 图谱 ID（展开/卡片 API 必需）
+  searchNodes?: string[];    // 搜索节点名，用于左右固定布局
 }
 ```
 
 ### GraphColors（颜色配置）
 
-```typescript
-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;
-}
-```
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| nodeLabelColor | `string` | `#000` | 节点标签文字颜色 |
+| nodeLabelFontSize | `number` | `16` | 节点标签字体大小 |
+| edgeLabelColor | `string` | `#666` | 边标签文字颜色 |
+| edgeLabelFontSize | `number` | `16` | 边标签字体大小 |
+| uriNodeColor | `string` | `#f7de63` | URI 类型节点背景色 |
+| normalNodeColor | `string` | `#1890FF` | 普通节点背景色 |
+| nodeBorderHoverColor | `string` | `#0d6ac2` | 节点边框悬停颜色 |
+| edgeDefaultColor | `string` | `#a29e9e` | 边默认颜色 |
+| edgeHoverColor | `string` | `#145AFD` | 边悬停颜色 |
+| pathHighlightColor | `string` | `#145AFD` | 路径高亮颜色 |
+| pathNodeColor | `string` | `#145AFD` | 路径节点颜色 |
 
 ### 颜色配置示例
 
@@ -346,6 +359,7 @@ interface GraphColors {
   data={data}
   colors={{
     nodeLabelColor: '#333',
+    nodeLabelFontSize: 18,
     edgeLabelColor: '#999',
     normalNodeColor: '#52c41a',
     uriNodeColor: '#faad14',
@@ -357,14 +371,31 @@ interface GraphColors {
 
 ## 图谱布局
 
-组件支持多种布局算法：
+组件支持 8 种布局算法，可通过 ActionBar 布局按钮切换：
+
+| 布局名称 | 说明 | 适用场景 |
+|---------|------|---------|
+| cose-bilkent | 力导向布局（默认） | 通用，适合大型图 |
+| fcose | 快速力导向布局 | 平衡速度与视觉效果 |
+| cose | 力导向布局 | 中大型图 |
+| cise | 圆形弹簧嵌入布局 | 聚类分组图 |
+| grid | 网格布局 | 规整排列 |
+| circle | 圆环布局 | 环状结构 |
+| breadthfirst | 层级布局 | 树形/层级结构 |
+| concentric | 同心圆布局 | 辐射状关系 |
+
+> 节点展开时内部使用 concentric 环形动画布局，子节点围绕当前节点分布，并自动寻找画布空白区域避免重叠。
+
+## 数据导出
+
+支持 4 种格式导出：
 
-| 布局名称 | 说明 |
-|---------|------|
-| cose-bilkent | 力导向布局（默认） |
-| cise | 聚类布局 |
-| fcose | 快速力导向布局 |
-| storm | 风暴布局 |
+| 格式 | 说明 |
+|------|------|
+| JSON | 完整图谱数据导出 |
+| Excel | 节点/边数据表格导出 |
+| PNG | 画布截图（白色背景） |
+| JPG | 画布截图 |
 
 ## License