bim_engine/docs/utils/icon-manager.md

# Icon Manager 图标管理器文档

> 本文档详细描述 Icon Manager 图标管理工具的实现细节,包括 API、使用方式、图标清单等,供 AI 根据文档重现功能。

---

## 1. 工具概述

### 1.1 基本信息
- **工具名称**: `IconManager`
- **文件路径**: `src/utils/icon-manager.ts`
- **导出函数**: `getIcon(name: string): string`
- **用途**: 统一管理所有 SVG 图标资源,提供通过名称获取图标的接口
- **特点**: 单一职责,简单易用,支持默认图标回退

### 1.2 设计目标
- **统一管理**: 所有图标集中在一个文件中管理,避免重复和不一致
- **简化使用**: 通过简单的函数调用获取图标,无需在各处重复 SVG 代码
- **类型安全**: SVG 作为字符串存储,可直接用于 innerHTML 或图标属性
- **容错机制**: 当请求的图标不存在时,返回默认图标而不是报错

---

## 2. API 文档

### 2.1 getIcon 函数

```typescript
function getIcon(name: string): string
```

**参数**:
- `name`: string - 图标名称(中文)

**返回值**:
- string - SVG 图标的完整字符串

**行为**:
1. 从 `ICONS` 对象中查找对应名称的图标
2. 如果找到,返回该图标的 SVG 字符串
3. 如果未找到,在控制台输出警告并返回默认图标

**示例**:
```typescript
import { getIcon } from '../../utils/icon-manager';

// 获取测量图标
const measureIcon = getIcon('测量');

// 获取不存在的图标(会返回默认图标并警告)
const unknownIcon = getIcon('不存在的图标');
// 控制台输出: [IconManager] Icon "不存在的图标" not found, using default icon
```

---

## 3. 图标清单

### 3.1 来自 assets 的图标 (48x48)

这些图标从 `src/assets/` 目录中的 SVG 文件简化而来,用于 toolbar 和主要功能按钮:

| 图标名称 | 用途 | 原始文件 |
|---------|------|----------|
| 测量 | 测量工具 | 测量.svg |
| 地图 | 地图视图/平面图 | 地图.svg |
| 框选放大 | 框选缩放 | 框选放大.svg |
| 漫游 | 漫游模式 | 漫游.svg |
| 目录树 | 构件树 | 目录树.svg |
| 剖切 | 剖切菜单 | 剖切.svg |
| 剖切盒 | 剖切盒 | 剖切盒.svg |
| 全屏 | 全屏模式 | 全屏.svg |
| 设置 | 设置面板 | 设置.svg |
| 拾曲面剖切 | 拾取曲面剖切 | 拾曲面剖切.svg |
| 轴向剖切 | 轴向剖切 | 轴向剖切.svg |
| 主视角 | 主视角/首页 | 主视角.svg |
| 文档 | 文档/属性 | 地图 – 1.svg |

### 3.2 测量相关图标 (32x32)

用于测量面板的各种测量方式:

| 图标名称 | 用途 |
|---------|------|
| 标高 | 标高测量 |
| 距离 | 距离测量 |
| 最小距离 | 最小距离测量 |
| 激光边距 | 激光边距测量 |
| 角度 | 角度测量 |
| 坡度 | 坡度测量 |
| 体积 | 体积测量 |
| 空间体积 | 空间体积测量 |

### 3.3 通用图标 (24x24)

常用的 UI 图标:

| 图标名称 | 用途 |
|---------|------|
| close | 关闭 |
| check | 勾选/确认 |
| warning | 警告 |
| error | 错误 |
| success | 成功 |
| plus | 加号/新增 |
| minus | 减号/删除 |
| arrowUp | 向上箭头 |
| arrowDown | 向下箭头 |
| arrowLeft | 向左箭头 |
| arrowRight | 向右箭头 |
| search | 搜索 |
| refresh | 刷新 |
| delete | 删除 |
| edit | 编辑 |
| save | 保存 |
| expand | 展开 |
| collapse | 收起 |

### 3.4 默认图标

| 图标名称 | 用途 |
|---------|------|
| default | 当请求的图标不存在时返回 |

---

## 4. 使用场景

### 4.1 在按钮配置中使用

```typescript
import { getIcon } from '../../../utils/icon-manager';

export const createMeasureButton = (engine: BimEngine): ButtonConfig => {
    return {
        id: 'measure',
        groupId: 'group-1',
        type: 'button',
        label: 'toolbar.measure',
        icon: getIcon('测量'),  // 使用图标管理器
        onClick: () => {
            engine.measure?.show();
        }
    };
};
```

### 4.2 在组件中使用

```typescript
import { getIcon } from '../../utils/icon-manager';

export class WalkControlPanel implements IBimComponent {
    private getIconSVG(type: string): string {
        const icons: Record<string, string> = {
            'plan-view': getIcon('地图'),
            'path': getIcon('地图'),
            'walk': getIcon('漫游')
        };
        return icons[type] || '';
    }

    private createIconButton(type: string, onClick: () => void): HTMLButtonElement {
        const btn = document.createElement('button');
        btn.className = `walk-icon-btn walk-icon-btn-${type}`;
        btn.innerHTML = this.getIconSVG(type);
        btn.addEventListener('click', onClick);
        return btn;
    }
}
```

### 4.3 在树节点中使用

```typescript
import { getIcon } from '../../utils/icon-manager';

const treeData: TreeNodeConfig[] = [
    {
        id: 'level-1',
        label: '一层',
        icon: getIcon('目录树'),
        children: [...]
    }
];
```

---

## 5. SVG 简化规范

### 5.1 简化原则

从 assets 目录中的 SVG 文件简化时,遵循以下原则:

1. **保留核心路径**:只保留 `<path>` 元素及其 `d` 属性
2. **移除冗余属性**:删除 `<defs>`, `<clipPath>`, `<style>`, `<g>` 等非必要元素
3. **保持颜色属性**:保留 `fill="currentColor"` 以支持主题颜色
4. **统一尺寸**:根据用途设置合适的 `viewBox` 和 `width/height`
5. **简化变换**:如果有 `transform`,尽量简化或合并到路径中

### 5.2 简化示例

**原始 SVG (从 assets/测量.svg)**:
```xml
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="48" height="48" viewBox="0 0 48 48">
  <defs>
    <clipPath id="clip-path">
      <rect width="48" height="48" fill="none"/>
    </clipPath>
  </defs>
  <g id="测量" clip-path="url(#clip-path)">
    <path d="M0,28.207H3.429v3.526H44.571V28.207H48v7.052H0ZM0,3.526v14.1a3.478,3.478,0,0,0,3.429,3.526H6.857V17.629h3.429v3.526h3.429V17.629h3.429v3.526h3.429V10.578H24V21.155h3.429V17.629h3.429v3.526h3.429V17.629h3.429v3.526h3.429V10.578h3.429V21.155A3.478,3.478,0,0,0,48,17.629V3.526A3.478,3.478,0,0,0,44.571,0H3.429A3.478,3.478,0,0,0,0,3.526Z" transform="translate(0 5.456)" fill="#000"/>
  </g>
</svg>
```

**简化后 (在 icon-manager.ts 中)**:
```typescript
测量: '<svg width="48" height="48" viewBox="0 0 48 48"><path fill="currentColor" d="M0,28.207H3.429v3.526H44.571V28.207H48v7.052H0ZM0,3.526v14.1a3.478,3.478,0,0,0,3.429,3.526H6.857V17.629h3.429v3.526h3.429V17.629h3.429v3.526h3.429V10.578H24V21.155h3.429V17.629h3.429v3.526h3.429V17.629h3.429v3.526h3.429V10.578h3.429V21.155A3.478,3.478,0,0,0,48,17.629V3.526A3.478,3.478,0,0,0,44.571,0H3.429A3.478,3.478,0,0,0,0,3.526Z" transform="translate(0 5.456)"/></svg>',
```

**关键变化**:
- 移除了 `xmlns`, `xmlns:xlink`, `<defs>`, `<clipPath>`, `<g>` 等
- 将 `fill="#000"` 改为 `fill="currentColor"` 以支持主题
- 保留了核心的 `<path>` 和 `viewBox`

---

## 6. 图标尺寸规范

### 6.1 尺寸分类

根据使用场景,图标分为三种尺寸:

1. **48x48**: 主要功能按钮(toolbar、工具栏)
2. **32x32**: 测量工具图标
3. **24x24**: 通用 UI 图标(关闭、展开等)

### 6.2 与 CSS 的配合

图标尺寸在 CSS 中可以被覆盖:

```css
/* Toolbar 按钮图标 */
.opt-btn-icon svg {
    width: 100%;
    height: 100%;
}

/* 漫游控制面板按钮图标 */
.walk-icon-btn svg {
    width: 32px;
    height: 32px;
}
```

实际显示尺寸由 CSS 控制,SVG 的 `width` 和 `height` 属性主要用于:
1. 定义默认尺寸
2. 计算宽高比
3. 作为 `viewBox` 的参考

---

## 7. 添加新图标

### 7.1 添加流程

1. **准备 SVG 文件**:
   - 将新图标文件放到 `src/assets/` 目录
   - 或直接获取 SVG 代码

2. **简化 SVG**:
   - 按照 5.1 节的简化原则处理 SVG
   - 确保 `fill="currentColor"` 以支持主题
   - 设置合适的尺寸

3. **添加到 ICONS 对象**:
   ```typescript
   const ICONS: Record<string, string> = {
       // ... 现有图标
       新图标名称: '<svg width="48" height="48" viewBox="0 0 48 48"><path fill="currentColor" d="..."/></svg>',
   };
   ```

4. **使用新图标**:
   ```typescript
   const icon = getIcon('新图标名称');
   ```

### 7.2 命名规范

- **使用中文名称**:便于理解和维护
- **描述功能**:名称应清晰描述图标用途
- **避免重复**:检查是否已存在类似图标

**推荐命名**:
- ✅ 好的命名: `测量`, `地图`, `全屏`, `剖切盒`
- ❌ 不好的命名: `icon1`, `svg2`, `btn_icon`

---

## 8. 实现细节(供 AI 重现)

### 8.1 核心数据结构

```typescript
const ICONS: Record<string, string> = {
    // key: 图标名称(中文)
    // value: SVG 字符串(完整的 <svg>...</svg>)
};
```

### 8.2 获取逻辑

```typescript
export function getIcon(name: string): string {
    const icon = ICONS[name];

    if (!icon) {
        console.warn(`[IconManager] Icon "${name}" not found, using default icon`);
        return ICONS.default;
    }

    return icon;
}
```

**关键点**:
1. 简单的字典查找
2. 未找到时返回默认图标而不是 `undefined`
3. 在控制台输出警告信息,便于调试

### 8.3 为什么不使用枚举?

设计选择:使用字符串而不是 TypeScript 枚举

**原因**:
1. **简化使用**:直接传中文字符串,更直观
2. **灵活性**:可以动态添加图标而不需要修改类型定义
3. **国际化友好**:中文名称与 UI 文案保持一致
4. **降低耦合**:使用方不需要导入枚举类型

---

## 9. 与主题系统的配合

### 9.1 currentColor 属性

所有图标使用 `fill="currentColor"`,这样图标颜色会继承父元素的 `color` 属性:

```typescript
测量: '<svg width="48" height="48" viewBox="0 0 48 48"><path fill="currentColor" d="..."/></svg>',
```

### 9.2 在 CSS 中控制颜色

```css
.opt-btn-icon {
    color: var(--bim-icon-color, #ccc);
}

.opt-btn-icon svg {
    fill: currentColor;  /* 继承父元素的 color */
}
```

### 9.3 主题变更时的自动适配

当主题颜色变更时,只需更新 CSS 变量,所有图标会自动适配新颜色:

```typescript
// 在 setTheme 中
element.style.setProperty('--bim-icon-color', theme.icon ?? '#ccc');
// 所有使用 currentColor 的图标自动更新颜色
```

---

## 10. 最佳实践

### 10.1 使用建议

**✅ 推荐做法**:
```typescript
// 在组件顶部导入
import { getIcon } from '../../utils/icon-manager';

// 在需要时调用
const icon = getIcon('测量');
button.innerHTML = icon;
```

**❌ 避免做法**:
```typescript
// 不要在组件中硬编码 SVG
const icon = '<svg>...</svg>';  // 不推荐

// 不要重复定义相同的图标
const myIcon = '<svg>...</svg>';  // 应该使用 getIcon()
```

### 10.2 性能考虑

- **字符串查找很快**:`ICONS` 对象的查找是 O(1) 操作
- **无需缓存**:图标字符串很小,不需要额外的缓存机制
- **按需使用**:只在需要时调用 `getIcon()`,不需要预加载所有图标

### 10.3 维护建议

1. **定期整理**:删除不再使用的图标
2. **统一风格**:新增图标应与现有图标风格一致
3. **文档同步**:添加新图标时更新本文档的图标清单
4. **命名规范**:使用清晰、一致的中文命名

---

## 11. 更新记录

| 日期       | 修改内容                                  | 修改人       |
| ---------- | ----------------------------------------- | ------------ |
| 2025-12-25 | 创建图标管理器,整合所有 SVG 图标资源     | AI Assistant |
| 2025-12-25 | 添加"文档"图标,替换所有 toolbar 按钮图标 | AI Assistant |