web-map/docs/Canvas绘制技术详解.md

# Canvas 2D 绘制技术详解

## 📖 概述

本文档详细分析场景编辑器中的自定义绘制函数，这些函数基于 **HTML5 Canvas 2D API** 在浏览器页面上绘制各种图形元素（点位、路线、区域、机器人）。

## 🎯 核心技术栈

### 1. HTML5 Canvas 2D API

- **技术原理**：Canvas 是 HTML5 提供的位图绘制 API
- **绘制方式**：使用 JavaScript 在 Canvas 画布上逐像素绘制
- **坐标系统**：左上角为原点 (0,0)，X轴向右，Y轴向下
- **绘制上下文**：通过 `CanvasRenderingContext2D` 对象进行所有绘制操作

### 2. Meta2D 引擎集成

- **自定义绘制**：通过 `registerCanvasDraw()` 注册自定义绘制函数
- **图形对象**：每个绘制函数接收 `MapPen` 对象，包含图形的所有属性
- **渲染时机**：引擎在每次重绘时自动调用对应的绘制函数

---

## 🎨 绘制函数详细分析

### 1. 点位绘制函数 `drawPoint()`

#### 函数签名和参数

```typescript
function drawPoint(ctx: CanvasRenderingContext2D, pen: MapPen): void;
```

#### 代码逐行分析

```typescript
// 1. 获取全局主题配置
const theme = sTheme.editor;
```

**分析**：从全局主题服务获取编辑器主题配置，用于确定颜色、样式等视觉属性。

```typescript
// 2. 从计算属性中提取绘制参数
const { active, iconSize: r = 0, fontSize = 14, lineHeight = 1.5, fontFamily } = pen.calculative ?? {};
```

**分析**：

- `active`：图形是否处于选中状态
- `iconSize`：图标大小，重命名为 `r`（半径）
- `fontSize/lineHeight/fontFamily`：文本绘制参数

```typescript
// 3. 获取世界坐标系下的矩形区域
const { x = 0, y = 0, width: w = 0, height: h = 0 } = pen.calculative?.worldRect ?? {};
```

**分析**：Meta2D 引擎会自动计算图形在世界坐标系下的实际位置和大小。

```typescript
// 4. 获取业务属性
const { type } = pen.point ?? {};
const { label = '' } = pen ?? {};
```

```typescript
// 5. 保存当前画布状态
ctx.save();
```

**分析**：`save()` 保存当前的绘制状态（变换矩阵、样式等），避免影响其他图形。

#### 小点位绘制（类型1-9）

```typescript
switch (type) {
  case MapPointType.普通点:
  case MapPointType.等待点:
  case MapPointType.避让点:
  case MapPointType.临时避让点:
    // 绘制圆角菱形
    ctx.beginPath();
    ctx.moveTo(x + w / 2 - r, y + r);
    ctx.arcTo(x + w / 2, y, x + w - r, y + h / 2 - r, r);
    ctx.arcTo(x + w, y + h / 2, x + w / 2 + r, y + h - r, r);
    ctx.arcTo(x + w / 2, y + h, x + r, y + h / 2 + r, r);
    ctx.arcTo(x, y + h / 2, x + r, y + h / 2 - r, r);
    ctx.closePath();
```

**分析**：

- `beginPath()`：开始新的绘制路径
- `moveTo()`：移动画笔到起始点
- `arcTo()`：绘制圆弧连接线，创建圆角效果
- `closePath()`：闭合路径形成完整图形

```typescript
// 填充背景色
ctx.fillStyle = get(theme, `point-s.fill-${type}`) ?? '';
ctx.fill();

// 绘制边框
ctx.strokeStyle = get(theme, active ? 'point-s.strokeActive' : 'point-s.stroke') ?? '';
```

**分析**：根据点位类型和激活状态设置不同的填充色和边框色。

#### 临时避让点特殊标记

```typescript
if (type === MapPointType.临时避让点) {
  ctx.lineCap = 'round'; // 设置线条端点为圆形
  ctx.beginPath();
  // 绘制8个短线标记，形成放射状效果
  ctx.moveTo(x + 0.66 * r, y + h / 2 - 0.66 * r);
  ctx.lineTo(x + r, y + h / 2 - r);
  // ... 其他7个方向的短线
}
```

**分析**：在菱形的8个方向绘制短线，形成特殊的视觉标识。

#### 大点位绘制（类型11+）

```typescript
case MapPointType.电梯点:
case MapPointType.自动门点:
case MapPointType.充电点:
case MapPointType.停靠点:
case MapPointType.动作点:
case MapPointType.禁行点:
  ctx.roundRect(x, y, w, h, r);  // 绘制圆角矩形
  ctx.strokeStyle = get(theme, active ? 'point-l.strokeActive' : 'point-l.stroke') ?? '';
  ctx.stroke();
```

**分析**：大点位使用圆角矩形，通过 `roundRect()` API 一次性绘制。

#### 文本标签绘制

```typescript
// 设置文本样式
ctx.fillStyle = get(theme, 'color') ?? '';
ctx.font = `${fontSize}px/${lineHeight} ${fontFamily}`;
ctx.textAlign = 'center'; // 水平居中
ctx.textBaseline = 'top'; // 垂直顶部对齐

// 在点位上方绘制标签
ctx.fillText(label, x + w / 2, y - fontSize * lineHeight);
```

```typescript
// 恢复画布状态
ctx.restore();
```

---

### 2. 路线绘制函数 `drawLine()`

#### 核心绘制逻辑

```typescript
// 1. 获取路线的两个端点坐标
const [p1, p2] = pen.calculative?.worldAnchors ?? [];
const { x: x1 = 0, y: y1 = 0 } = p1 ?? {};
const { x: x2 = 0, y: y2 = 0 } = p2 ?? {};
```

```typescript
// 2. 获取路线属性
const { type, direction = 1, pass = 0, c1, c2 } = pen.route ?? {};
const { x: dx1 = 0, y: dy1 = 0 } = c1 ?? {}; // 控制点1偏移
const { x: dx2 = 0, y: dy2 = 0 } = c2 ?? {}; // 控制点2偏移
```

#### 路线类型绘制

```typescript
ctx.moveTo(x1, y1); // 移动到起点
switch (type) {
  case MapRouteType.直线:
    ctx.lineTo(x2, y2); // 直接连线到终点
    break;

  case MapRouteType.二阶贝塞尔曲线:
    // 使用一个控制点绘制曲线
    ctx.quadraticCurveTo(x1 + dx1 * s, y1 + dy1 * s, x2, y2);
    break;

  case MapRouteType.三阶贝塞尔曲线:
    // 使用两个控制点绘制更复杂的曲线
    ctx.bezierCurveTo(x1 + dx1 * s, y1 + dy1 * s, x2 + dx2 * s, y2 + dy2 * s, x2, y2);
    break;
}
```

**贝塞尔曲线原理**：

- **二阶贝塞尔曲线**：由起点、一个控制点、终点定义的曲线
- **三阶贝塞尔曲线**：由起点、两个控制点、终点定义的更灵活曲线
- **数学公式**：基于参数方程计算曲线上的每个点

#### 禁行路线绘制

```typescript
if (pass === MapRoutePassType.禁行) {
  ctx.setLineDash([s * 5]); // 设置虚线样式
}
ctx.stroke(); // 绘制路线
```

#### 方向箭头绘制

```typescript
// 1. 计算箭头角度
let r = (() => {
  switch (type) {
    case MapRouteType.直线:
      return Math.atan2(y2 - y1, x2 - x1); // 直线的角度
    case MapRouteType.二阶贝塞尔曲线:
      // 根据控制点计算切线角度
      return direction < 0 ? Math.atan2(dy1 * s, dx1 * s) : Math.atan2(y2 - y1 - dy1 * s, x2 - x1 - dx1 * s);
    // ...
  }
})();
```

```typescript
// 2. 移动坐标系到箭头位置
if (direction < 0) {
  ctx.translate(x1, y1); // 反向箭头在起点
} else {
  ctx.translate(x2, y2); // 正向箭头在终点
  r += Math.PI; // 旋转180度
}

// 3. 绘制箭头（两条线段形成尖角）
ctx.moveTo(Math.cos(r + Math.PI / 5) * s * 10, Math.sin(r + Math.PI / 5) * s * 10);
ctx.lineTo(0, 0);
ctx.lineTo(Math.cos(r - Math.PI / 5) * s * 10, Math.sin(r - Math.PI / 5) * s * 10);
```

**箭头绘制原理**：

- 使用三角函数计算箭头两条边的端点
- `Math.PI / 5` (36度) 是箭头的张开角度
- 通过坐标变换将箭头定位到正确位置和角度

---

### 3. 区域绘制函数 `drawArea()`

#### 矩形区域绘制

```typescript
// 1. 绘制填充矩形
ctx.rect(x, y, w, h); // 定义矩形路径
ctx.fillStyle = get(theme, `area.fill-${type}`) ?? ''; // 设置填充色
ctx.fill(); // 填充矩形

// 2. 绘制边框
ctx.strokeStyle = get(theme, active ? 'area.strokeActive' : `area.stroke-${type}`) ?? '';
ctx.stroke(); // 绘制边框
```

#### 区域标签

```typescript
// 在区域上方居中显示标签
ctx.fillStyle = get(theme, 'color') ?? '';
ctx.font = `${fontSize}px/${lineHeight} ${fontFamily}`;
ctx.textAlign = 'center';
ctx.textBaseline = 'top';
ctx.fillText(label, x + w / 2, y - fontSize * lineHeight);
```

---

### 4. 机器人绘制函数 `drawRobot()`

#### 机器人本体绘制

```typescript
const ox = x + w / 2; // 机器人中心X坐标
const oy = y + h / 2; // 机器人中心Y坐标

// 绘制椭圆形机器人
ctx.ellipse(ox, oy, w / 2, h / 2, 0, 0, Math.PI * 2);
ctx.fillStyle = get(theme, 'robot.fill') ?? '';
ctx.fill();
ctx.strokeStyle = get(theme, 'robot.stroke') ?? '';
ctx.stroke();
```

#### 路径轨迹绘制

```typescript
if (path?.length) {
  // 设置路径样式
  ctx.strokeStyle = get(theme, 'robot.line') ?? '';
  ctx.lineCap = 'round'; // 圆形线帽
  ctx.lineWidth = s * 4; // 粗线条
  ctx.setLineDash([s * 5, s * 10]); // 虚线样式

  // 坐标变换：移动到机器人中心并旋转
  ctx.translate(ox, oy);
  ctx.rotate((-deg * Math.PI) / 180);

  // 绘制路径线条
  ctx.beginPath();
  ctx.moveTo(0, 0);
  path.forEach((d) => ctx.lineTo(d.x * s, d.y * s));
  ctx.stroke();
}
```

#### 路径终点箭头

```typescript
// 计算路径最后两个点的方向
const { x: ex1 = 0, y: ey1 = 0 } = nth(path, -1) ?? {}; // 最后一个点
const { x: ex2 = 0, y: ey2 = 0 } = nth(path, -2) ?? {}; // 倒数第二个点
const r = Math.atan2(ey1 - ey2, ex1 - ex2) + Math.PI;

// 在路径终点绘制箭头
ctx.translate(ex1 * s, ey1 * s);
ctx.beginPath();
ctx.moveTo(Math.cos(r + Math.PI / 4) * s * 10, Math.sin(r + Math.PI / 4) * s * 10);
ctx.lineTo(0, 0);
ctx.lineTo(Math.cos(r - Math.PI / 4) * s * 10, Math.sin(r - Math.PI / 4) * s * 10);
ctx.stroke();
```

---

## 🔧 Canvas 2D API 核心方法说明

### 路径绘制方法

| 方法                                          | 功能               | 示例                 |
| --------------------------------------------- | ------------------ | -------------------- |
| `beginPath()`                                 | 开始新的绘制路径   | 每次绘制新图形前调用 |
| `moveTo(x, y)`                                | 移动画笔到指定位置 | 设置绘制起点         |
| `lineTo(x, y)`                                | 画直线到指定位置   | 绘制线段             |
| `arcTo(x1, y1, x2, y2, r)`                    | 绘制圆弧连接       | 创建圆角效果         |
| `quadraticCurveTo(cpx, cpy, x, y)`            | 二阶贝塞尔曲线     | 简单曲线             |
| `bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y)` | 三阶贝塞尔曲线     | 复杂曲线             |
| `rect(x, y, w, h)`                            | 矩形路径           | 绘制矩形             |
| `ellipse(x, y, rx, ry, rotation, start, end)` | 椭圆路径           | 绘制椭圆/圆形        |
| `closePath()`                                 | 闭合当前路径       | 连接起点和终点       |

### 样式设置方法

| 属性/方法            | 功能             | 示例                            |
| -------------------- | ---------------- | ------------------------------- |
| `fillStyle`          | 设置填充颜色     | `ctx.fillStyle = '#ff0000'`     |
| `strokeStyle`        | 设置描边颜色     | `ctx.strokeStyle = '#0000ff'`   |
| `lineWidth`          | 设置线条宽度     | `ctx.lineWidth = 2`             |
| `lineCap`            | 设置线条端点样式 | `'round'`, `'square'`, `'butt'` |
| `setLineDash([...])` | 设置虚线样式     | `ctx.setLineDash([5, 5])`       |

### 变换方法

| 方法                             | 功能         | 说明           |
| -------------------------------- | ------------ | -------------- |
| `translate(x, y)`                | 平移坐标系   | 移动原点位置   |
| `rotate(angle)`                  | 旋转坐标系   | 按弧度旋转     |
| `setTransform(a, b, c, d, e, f)` | 重置变换矩阵 | 恢复标准坐标系 |

### 状态管理方法

| 方法        | 功能         | 说明       |
| ----------- | ------------ | ---------- |
| `save()`    | 保存当前状态 | 压入状态栈 |
| `restore()` | 恢复之前状态 | 弹出状态栈 |

---

## 🎯 绘制流程总结

### 1. 标准绘制流程

```typescript
function customDraw(ctx: CanvasRenderingContext2D, pen: MapPen): void {
  // 1. 保存画布状态
  ctx.save();

  // 2. 提取绘制参数
  const { x, y, width, height } = pen.calculative?.worldRect ?? {};

  // 3. 设置样式属性
  ctx.fillStyle = '填充色';
  ctx.strokeStyle = '边框色';

  // 4. 创建绘制路径
  ctx.beginPath();
  // ... 具体绘制操作

  // 5. 执行绘制
  ctx.fill(); // 填充
  ctx.stroke(); // 描边

  // 6. 恢复画布状态
  ctx.restore();
}
```

### 2. 性能优化要点

- **状态管理**：及时调用 `save()` 和 `restore()` 避免状态污染
- **路径复用**：合理使用 `beginPath()` 清除之前的路径
- **批量绘制**：同类型图形可以合并绘制操作
- **避免重复计算**：缓存复杂的数学计算结果

---

## 📊 技术优势

### 1. Canvas 2D 的优势

- **高性能**：直接操作像素，渲染速度快
- **灵活性**：可以绘制任意复杂的图形
- **交互性**：支持鼠标事件检测和处理
- **兼容性**：现代浏览器完全支持

### 2. 自定义绘制的优势

- **个性化**：完全定制化的视觉效果
- **主题支持**：动态切换颜色主题
- **状态反馈**：不同状态显示不同样式
- **扩展性**：易于添加新的图形类型

---

## 🔚 结语

本场景编辑器通过 Canvas 2D API 实现了丰富的图形绘制功能，每个绘制函数都经过精心设计，既保证了视觉效果，又兼顾了性能表现。理解这些绘制原理对于进一步扩展和优化编辑器功能具有重要意义。