@knotx/plugins-minimap

小地图插件，为 KnotX 提供画布导航功能。

安装

npm install @knotx/plugins-minimap

概述

Minimap 插件为 KnotX 提供了小地图功能，允许用户在大型画布中快速导航。该插件基于 interactjs 库实现，提供了缩放、平移、视窗控制等功能。

实现原理

Minimap 插件的核心实现原理：

1. 节点映射：将画布上的节点映射到小地图的比例尺中
2. 视窗同步：实时同步主画布和小地图的视窗状态
3. 交互控制：支持在小地图上拖拽和点击进行导航
4. 缩放控制：提供缩放按钮和重置功能

依赖关系

核心依赖

• @knotx/core：提供基础插件架构
• @knotx/decorators：提供装饰器支持
• interactjs：提供交互功能
• rxjs：提供响应式编程支持

插件依赖

• @knotx/plugins-canvas：获取画布变换状态和容器信息

API 文档

主要类

Minimap

小地图插件的主要类，继承自 BasePlugin。

export class Minimap extends BasePlugin<'minimap', MinimapConfig> {
  name = 'minimap' as const
}

配置选项

MinimapConfig

export interface MinimapConfig {
  /** 小地图宽度 */
  width?: number
  /** 小地图高度 */
  height?: number
  /** 节点颜色 */
  nodeColor?: string | ((node: Node) => string)
  /** 视图区域背景颜色 */
  maskColor?: string
  /** 视图区域边框颜色 */
  viewBoxColor?: string
  /** 显示小地图控制按钮 */
  showControls?: boolean
  /** 是否可缩放 */
  zoomable?: boolean
  /** 是否可平移 */
  pannable?: boolean
  /** 与容器的内边距 */
  padding?: number
  /** 节点圆角 */
  nodeBorderRadius?: number
  /** 节点描边宽度 */
  nodeStrokeWidth?: number
  /** 节点描边颜色 */
  nodeStrokeColor?: string | ((node: Node) => string)
  /** 缩放步长 */
  zoomStep?: number
}

默认配置

const defaultProps: Required<Omit<MinimapConfig, 'nodeColor' | 'nodeStrokeColor'>> = {
  width: 200,
  height: 150,
  maskColor: 'rgba(240, 240, 240, 0.6)',
  viewBoxColor: '#4752E6',
  showControls: true,
  zoomable: true,
  pannable: true,
  padding: 12,
  nodeBorderRadius: 2,
  nodeStrokeWidth: 1,
  zoomStep: 0.2,
}

使用示例

基本用法

import { Minimap } from '@knotx/plugins-minimap'

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      width: 200,
      height: 150,
    },
  },
})

自定义样式

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      width: 250,
      height: 180,
      nodeColor: '#4A90E2',
      maskColor: 'rgba(255, 255, 255, 0.8)',
      viewBoxColor: '#FF6B6B',
      nodeBorderRadius: 4,
      nodeStrokeWidth: 2,
      nodeStrokeColor: '#333',
    },
  },
})

动态节点颜色

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      nodeColor: (node) => {
        // 根据节点类型返回不同颜色
        switch (node.type) {
          case 'start':
            return '#4CAF50'
          case 'end':
            return '#F44336'
          case 'process':
            return '#2196F3'
          default:
            return '#9E9E9E'
        }
      },
      nodeStrokeColor: (node) => {
        return node.selected ? '#FF9800' : 'transparent'
      },
    },
  },
})

禁用控制按钮

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      showControls: false,
      zoomable: false,
      pannable: true,
    },
  },
})

自定义尺寸和位置

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      width: 300,
      height: 200,
      padding: 20,
      zoomStep: 0.3,
    },
  },
})

高级功能

与 Canvas 插件集成

import { Canvas } from '@knotx/plugins-canvas'
import { Minimap } from '@knotx/plugins-minimap'

const engine = new Engine({
  plugins: [Canvas, Minimap],
  pluginConfig: {
    canvas: {
      minScale: 0.1,
      maxScale: 3,
    },
    minimap: {
      width: 200,
      height: 150,
    },
  },
})

监听小地图交互

class MinimapInteractionPlugin extends BasePlugin {
  @inject.canvas.transform()
  transform!: CanvasTransformState

  @subscribe.canvas.transform()
  onTransformChange(transform: CanvasTransformState) {
    console.log('Canvas transform changed:', transform)
    // 小地图会自动同步变换状态
  }
}

自定义小地图行为

class CustomMinimapPlugin extends BasePlugin {
  @inject.minimap.config()
  minimapConfig!: MinimapConfig

  @OnInit
  init() {
    // 动态调整小地图配置
    this.minimapConfig.nodeColor = (node) => {
      const isImportant = node.data?.important
      return isImportant ? '#FF5722' : '#607D8B'
    }
  }
}

样式自定义

CSS 类名

小地图提供了以下 CSS 类名用于样式自定义：

.knotx-minimap {
  /* 小地图容器 */
  border: 1px solid #ddd;
  border-radius: 4px;
  background: #fff;
}

.knotx-minimap__svg {
  /* SVG 容器 */
  cursor: crosshair;
}

.knotx-minimap__controls {
  /* 控制按钮容器 */
  display: flex;
  gap: 4px;
  margin-top: 8px;
}

.knotx-minimap__button {
  /* 控制按钮 */
  padding: 4px 8px;
  border: 1px solid #ccc;
  background: #f5f5f5;
  cursor: pointer;
}

.knotx-minimap__button:hover {
  background: #e0e0e0;
}

.knotx-minimap__button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

自定义样式示例

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      width: 200,
      height: 150,
      // 自定义视窗颜色
      viewBoxColor: '#FF6B6B',
      // 自定义蒙版颜色
      maskColor: 'rgba(255, 107, 107, 0.1)',
    },
  },
})

性能优化

节点渲染优化

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      // 使用固定颜色避免函数调用开销
      nodeColor: '#4A90E2',
      nodeStrokeColor: 'transparent',
      // 减少圆角以提高渲染性能
      nodeBorderRadius: 0,
    },
  },
})

交互优化

const engine = new Engine({
  plugins: [Minimap],
  pluginConfig: {
    minimap: {
      // 较小的缩放步长提供更平滑的体验
      zoomStep: 0.1,
      // 合适的尺寸平衡性能和可用性
      width: 180,
      height: 120,
    },
  },
})

文件目录结构

packages/plugins-minimap/
├── src/
│   ├── minimap.tsx             # 主要实现文件
│   └── index.ts               # 导出文件
├── dist/                      # 构建输出目录
├── package.json              # 包配置文件
├── build.config.ts           # 构建配置
├── tsconfig.json             # TypeScript 配置
├── eslint.config.mjs         # ESLint 配置
└── CHANGELOG.md              # 更新日志

核心文件说明

• minimap.tsx：包含 Minimap 插件的主要实现，包括节点映射、视窗同步和交互控制
• index.ts：导出 Minimap 类和相关类型定义

最佳实践

用户体验

1. 合适的尺寸：根据应用布局选择合适的小地图尺寸
2. 清晰的视觉反馈：使用对比度高的颜色区分不同元素
3. 平滑的交互：合理配置缩放步长和动画效果

性能优化

1. 固定颜色：对于大量节点，使用固定颜色而非动态函数
2. 简化样式：减少不必要的视觉效果以提高渲染性能
3. 合理尺寸：根据节点数量调整小地图尺寸

开发调试

1. 监听状态变化：在开发阶段监听变换状态变化
2. 测试交互：确保小地图与主画布的同步正常
3. 验证边界：测试极端缩放和平移情况

注意事项

1. 依赖关系：确保 Canvas 插件在 Minimap 插件之前加载
2. 性能考虑：大量节点时，小地图的渲染可能影响性能
3. 响应式设计：考虑在不同屏幕尺寸下的小地图显示
4. 浏览器兼容性：依赖 SVG 和现代 JavaScript 特性

许可证

MIT