FiDA_Front/src/components/Canvas/DepthCanvas/manager/brushes/README.md

<!-- https://github.com/tennisonchan/fabric-brush?tab=readme-ov-file -->
<!-- eraser_brush：https://unpkg.com/fabric@5.5.2/src/mixins/eraser_brush.mixin.js -->
# 笔刷系统使用指南

## 概述

这是一个基于插件架构的笔刷系统，允许轻松扩展和添加新的笔刷类型。整个系统由以下几个关键部分组成：

1. `BaseBrush` - 所有笔刷的基类
2. `BrushRegistry` - 笔刷注册表，用于管理所有笔刷
3. `BrushManager` - 笔刷管理器，处理笔刷的实例化和切换
4. `BrushStore` - 笔刷状态存储

## 如何添加新笔刷

添加新笔刷只需简单几步：

### 1. 创建新的笔刷类

最简单的方法是继承 `BaseBrush` 类。在 `types` 目录下创建你的笔刷文件：

```javascript
import { BaseBrush } from '../BaseBrush';

/**
 * 我的自定义笔刷
 */
export class MyCustomBrush extends BaseBrush {
  constructor(canvas, options = {}) {
    super(canvas, {
      id: 'my-custom-brush',
      name: '我的笔刷',
      description: '这是我自定义的笔刷',
      category: '自定义笔刷',
      ...options
    });
  }
  
  // 创建笔刷实例
  create() {
    // 创建底层fabric.js笔刷
    this.brush = new fabric.PencilBrush(this.canvas);
    // 配置笔刷
    this.configure(this.brush, this.options);
    return this.brush;
  }
  
  // 配置笔刷
  configure(brush, options = {}) {
    // 设置基本属性
    if (options.color) brush.color = options.color;
    if (options.width !== undefined) brush.width = options.width;
    if (options.opacity !== undefined) brush.opacity = options.opacity;
    
    // 设置自定义属性
    brush.strokeLineCap = 'round';
    brush.strokeLineJoin = 'round';
    // ...更多自定义设置
  }
}
```

### 2. 注册笔刷

有两种方式注册笔刷：

#### 方式一：使用BrushRegistry直接注册

```javascript
import { brushRegistry } from '../BrushRegistry';
import { MyCustomBrush } from './MyCustomBrush';

// 注册笔刷
brushRegistry.register('my-custom-brush', MyCustomBrush, {
  name: '我的笔刷',
  description: '这是我自定义的笔刷',
  category: '自定义笔刷'
});
```

#### 方式二：通过BrushManager注册

```javascript
import { BrushManager } from '../brushManager';
import { MyCustomBrush } from './MyCustomBrush';

// 获取BrushManager实例
const brushManager = new BrushManager({ canvas });

// 注册笔刷
brushManager.registerBrush('my-custom-brush', MyCustomBrush, {
  name: '我的笔刷',
  description: '这是我自定义的笔刷',
  category: '自定义笔刷'
});
```

### 3. 使用笔刷

注册笔刷后，可以在应用中使用它：

```javascript
// 切换到你的自定义笔刷
brushManager.setBrushType('my-custom-brush');
```

## 笔刷生命周期

每个笔刷有以下生命周期方法：

1. `constructor` - 创建笔刷类实例
2. `create` - 创建底层fabric.js笔刷实例
3. `configure` - 配置笔刷属性
4. `onSelected` - 笔刷被选中时调用
5. `onDeselected` - 笔刷被取消选中时调用
6. `destroy` - 销毁笔刷实例释放资源

## 示例：创建具有独特行为的笔刷

这个例子创建了一个"脉冲笔刷"，线条宽度会自动脉动变化：

```javascript
import { BaseBrush } from '../BaseBrush';

export class PulseBrush extends BaseBrush {
  constructor(canvas, options = {}) {
    super(canvas, {
      id: 'pulse',
      name: '脉动笔刷',
      description: '线条宽度会自动脉动变化',
      category: '特效笔刷',
      ...options
    });
    
    this.originalWidth = options.width || 5;
    this.pulseRate = options.pulseRate || 0.1;
    this.pulseAmount = options.pulseAmount || 3;
    this.pulseTimer = null;
  }
  
  create() {
    this.brush = new fabric.PencilBrush(this.canvas);
    this.configure(this.brush, this.options);
    
    // 覆盖鼠标按下方法，开始脉冲效果
    const originalMouseDown = this.brush.onMouseDown;
    this.brush.onMouseDown = (pointer, options) => {
      this.startPulse();
      return originalMouseDown.call(this.brush, pointer, options);
    };
    
    // 覆盖鼠标松开方法，停止脉冲效果
    const originalMouseUp = this.brush.onMouseUp;
    this.brush.onMouseUp = (options) => {
      this.stopPulse();
      return originalMouseUp.call(this.brush, options);
    };
    
    return this.brush;
  }
  
  configure(brush, options = {}) {
    if (options.width !== undefined) {
      this.originalWidth = options.width;
      brush.width = this.originalWidth;
    }
    
    if (options.color) {
      brush.color = options.color;
    }
    
    if (options.opacity !== undefined) {
      brush.opacity = options.opacity;
    }
    
    if (options.pulseRate !== undefined) {
      this.pulseRate = options.pulseRate;
    }
    
    if (options.pulseAmount !== undefined) {
      this.pulseAmount = options.pulseAmount;
    }
  }
  
  startPulse() {
    this.stopPulse();
    
    let phase = 0;
    this.pulseTimer = setInterval(() => {
      phase += this.pulseRate;
      const pulseFactor = Math.sin(phase) * this.pulseAmount;
      
      if (this.brush) {
        this.brush.width = Math.max(1, this.originalWidth + pulseFactor);
      }
    }, 50);
  }
  
  stopPulse() {
    if (this.pulseTimer) {
      clearInterval(this.pulseTimer);
      this.pulseTimer = null;
    }
  }
  
  onDeselected() {
    this.stopPulse();
  }
  
  destroy() {
    this.stopPulse();
    super.destroy();
  }
}
```

## 使用预设笔刷类型

系统内置了几种笔刷类型，可以直接使用：

- `pencil` - 基础铅笔笔刷
- `spray` - 喷枪笔刷
- `marker` - 马克笔笔刷
- `eraser` - 橡皮擦笔刷
- `texture` - 材质笔刷
- `watercolor` - 水彩笔刷
- `chalk` - 粉笔笔刷

## 高级功能

### 1. 使用分类组织笔刷

注册笔刷时可以指定类别，便于在UI中分组展示：

```javascript
brushRegistry.register('my-brush', MyBrushClass, { 
  category: '艺术笔刷' 
});
```

### 2. 自定义笔刷参数

可以为笔刷添加特殊参数，例如：

```javascript
// 笔刷类中
setGlowIntensity(intensity) {
  this.glowIntensity = intensity;
  // 更新笔刷效果
}

// 使用时
const neonBrush = brushManager.setBrushType('neon');
if (neonBrush && typeof neonBrush.setGlowIntensity === 'function') {
  neonBrush.setGlowIntensity(15);
}
```

## 常见问题

### 如何创建复杂的自定义笔刷效果？

对于复杂的效果，可以：

1. 覆盖fabric.js笔刷的关键方法，如`onMouseMove`
2. 使用自定义渲染器处理绘制
3. 结合Canvas API创建特殊效果

### 如何获取所有注册的笔刷？

```javascript
// 获取所有笔刷
const allBrushes = brushRegistry.getAllBrushes();

// 获取所有分类
const categories = brushRegistry.getCategories();

// 获取指定分类的笔刷
const artisticBrushes = brushRegistry.getBrushesByCategory('艺术笔刷');
```