@knotx/plugins-guideline

English | 中文

辅助线插件，为 KnotX 提供节点拖拽时的对齐提示功能。

安装

npm install @knotx/plugins-guideline
# or
pnpm add @knotx/plugins-guideline
# or
yarn add @knotx/plugins-guideline

概述

Guideline 插件为 KnotX 提供了智能的节点对齐辅助功能，在节点拖拽过程中实时检测并显示对齐辅助线。该插件支持多种对齐方式、自动吸附功能，并提供了优秀的性能和用户体验。

功能特性

• 🎯 智能对齐检测 - 实时检测节点之间的对齐关系
• 📏 多种对齐方式 - 支持左、右、中心、顶部、底部对齐
• 🧲 自动吸附功能 - 节点接近对齐位置时自动吸附到精确位置
• ⚡ 性能优化 - 仅在拖拽时计算和渲染辅助线
• 🎨 可自定义 - 支持自定义颜色、阈值等配置
• 🔄 响应式更新 - 基于 RxJS 实现响应式的状态管理

实现原理

Guideline 插件的核心实现原理：

1. 事件监听：监听节点的 draftOperation 事件，获取拖拽中的节点位置变化
2. 距离计算：实时计算拖拽节点与其他节点之间的距离关系
3. 对齐检测：在设定的阈值范围内检测各种对齐可能性
4. 辅助线生成：根据检测结果生成相应的垂直和水平辅助线
5. 自动吸附：当启用 snap 功能时，自动调整节点位置到精确的对齐位置
6. 渲染优化：在前景层渲染辅助线，确保视觉层级正确

依赖关系

核心依赖

• @knotx/core：提供基础插件架构和数据管理
• @knotx/decorators：提供装饰器支持
• rxjs：提供响应式编程支持

API 文档

主要类

Guideline

辅助线插件的主要类，继承自 BasePlugin。

export class Guideline extends BasePlugin {
  name = 'guideline' as const
}

配置选项

GuidelineConfig

export interface GuidelineConfig {
  /** 对齐阈值（像素），节点在此范围内将显示辅助线 */
  threshold?: number
  /** 辅助线颜色 */
  color?: string
  /** 辅助线宽度（像素） */
  lineWidth?: number
  /** 是否启用插件 */
  enabled?: boolean
  /** 是否启用自动吸附功能 */
  enableSnap?: boolean
}

类型定义

GuidelineItem

interface GuidelineItem {
  /** 辅助线类型 */
  type: 'vertical' | 'horizontal'
  /** 辅助线位置坐标 */
  position: number
  /** 可选的标签信息 */
  label?: string
}

使用示例

基本用法

import { Engine } from '@knotx/core'
import { Guideline } from '@knotx/plugins-guideline'

const engine = new Engine({
  container: { width: 800, height: 600, direction: 'horizontal' },
  plugins: [
    Guideline,
    // 其他插件...
  ],
})

自定义配置

const engine = new Engine({
  plugins: [Guideline],
  pluginConfig: {
    guideline: {
      threshold: 5,
      color: '#007ACC',
      lineWidth: 1,
      enabled: true,
      enableSnap: true,
    },
  },
})

与拖拽插件配合使用

import { Drag } from '@knotx/plugins-drag'
import { Guideline } from '@knotx/plugins-guideline'

const engine = new Engine({
  plugins: [Drag, Guideline],
  pluginConfig: {
    guideline: {
      threshold: 8,
      color: '#FF6B6B',
      enableSnap: true,
    },
  },
})

动态配置

const engine = new Engine({
  plugins: [Guideline],
})

// 运行时修改配置
engine.updatePluginConfig('guideline', {
  threshold: 10,
  color: '#4ECDC4',
  enableSnap: false,
})

配置选项

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | threshold | number | 5 | 对齐阈值（像素），节点在此范围内将显示辅助线 | | color | string | '#007ACC' | 辅助线颜色 | | lineWidth | number | 1 | 辅助线宽度（像素） | | enabled | boolean | true | 是否启用插件 | | enableSnap | boolean | true | 是否启用自动吸附功能 |

对齐类型

插件支持以下对齐类型：

垂直对齐

• 左边对齐 - 节点左边缘对齐
• 右边对齐 - 节点右边缘对齐
• 中心对齐 - 节点水平中心对齐
• 边缘对齐 - 一个节点的边缘与另一个节点的相对边缘对齐

水平对齐

• 顶部对齐 - 节点顶部对齐
• 底部对齐 - 节点底部对齐
• 中心对齐 - 节点垂直中心对齐
• 边缘对齐 - 一个节点的边缘与另一个节点的相对边缘对齐

工作原理

1. 监听节点的 draftOperation 事件
2. 当节点位置发生变化时，计算与其他节点的距离
3. 在阈值范围内时，生成相应的辅助线
4. Snap功能：如果启用，自动将节点位置调整到最近的对齐位置
5. 在 Layer.Foreground 层渲染辅助线
6. 拖拽结束时自动清除辅助线

高级功能

自定义辅助线样式

class CustomGuidelinePlugin extends BasePlugin {
  @OnInit
  init() {
    // 可以通过继承或配置来自定义辅助线的渲染样式
    const config = this.engine.getPluginConfig('guideline')
    config.color = this.getThemeColor()
    config.lineWidth = this.getLineWidth()
  }

  private getThemeColor(): string {
    // 根据主题返回不同的颜色
    return document.body.classList.contains('dark-theme') ? '#64FFDA' : '#007ACC'
  }

  private getLineWidth(): number {
    // 根据画布缩放级别调整线宽
    const scale = this.engine.getPluginData('canvas')?.transform?.scale || 1
    return Math.max(1, Math.round(2 / scale))
  }
}

性能优化配置

const engine = new Engine({
  plugins: [Guideline],
  pluginConfig: {
    guideline: {
      // 在大量节点场景下，适当增加阈值以减少计算
      threshold: 10,
      // 禁用自动吸附以提升性能
      enableSnap: false,
    },
  },
})

文件目录结构

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

核心文件说明

• plugin.tsx：包含 Guideline 插件的主要实现，包括对齐检测算法、辅助线渲染和自动吸附功能
• index.ts：导出 Guideline 类和相关类型定义

最佳实践

性能优化

1. 合理设置阈值：根据使用场景调整 threshold 值，过小的阈值会增加计算负担
2. 按需启用吸附：在精确定位重要的场景启用 enableSnap，否则可以禁用以提升性能
3. 节点数量考虑：在节点数量较多的场景下，考虑适当增加阈值或优化渲染策略

用户体验

1. 视觉一致性：确保辅助线颜色与整体设计风格保持一致
2. 响应性配置：根据画布缩放级别动态调整线宽和阈值
3. 渐进式增强：在移动设备上可以考虑禁用或简化辅助线功能

集成建议

1. 与拖拽插件配合：建议与 @knotx/plugins-drag 插件一起使用以获得最佳体验
2. 主题适配：支持明暗主题切换时，动态调整辅助线颜色
3. 快捷键支持：可以考虑添加快捷键来临时禁用/启用辅助线功能

示例

查看 apps/playground/src/examples/basic/guideline.tsx 中的示例代码，了解如何使用辅助线插件。

注意事项

1. 性能考虑：在大量节点的场景下，频繁的对齐计算可能影响性能
2. 事件优先级：确保与其他交互插件的事件处理顺序正确
3. 内存管理：插件会自动清理不再需要的辅助线，无需手动管理
4. 浏览器兼容性：使用了现代浏览器特性，确保目标浏览器支持

许可证

MIT © boenfu