npm package: @knotx/plugins-guideline
Description: Guideline Plugin for Knotx
Author: boenfu
Latest version: 0.5.10

# @knotx/plugins-guideline

[English](./README.en.md) | 中文

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

## 安装

```bash
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`。

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

### 配置选项

#### GuidelineConfig

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

### 类型定义

#### GuidelineItem

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

## 使用示例

### 基本用法

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

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

### 自定义配置

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

### 与拖拽插件配合使用

```typescript
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,
    },
  },
})
```

### 动态配置

```typescript
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. 拖拽结束时自动清除辅助线

## 高级功能

### 自定义辅助线样式

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

### 性能优化配置

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