# 图标系统

> **首选 `MSO_SHAPE.*` —— PowerPoint 原生形状,矢量、可编辑、配色随主题。** 复杂图标(齿轮、放大镜、文件夹等无对应 MSO_SHAPE)再走 `render_icon.py` 用 unicode 字形栅格化为 PNG。

## A. MSO_SHAPE 图标目录

```python
from pptx.enum.shapes import MSO_SHAPE
```

### 标记类 (放在 bullet 前 / 标题旁)

| 用途 | MSO_SHAPE | 说明 |
|-----|-----------|------|
| 圆点 bullet | `OVAL` | 0.18×0.18 in,实心填充 |
| 方点 bullet | `RECTANGLE` | 0.16×0.16 in,实心 |
| 钻石点 | `DIAMOND` | 0.2×0.2 in |
| 对号 ✓ | `CHEVRON` 旋转 / 或用字形 | MSO 没有专门"check"形;用字形更清晰 |
| 加号 + | `MATH_PLUS` | 强调"新增"语境 |
| 星 ★ | `STAR_5_POINT` | 重点项;不要每页都用 |
| 心 | `HEART` | 用户向 / 软话题 |

### 箭头类 (流程 / 趋势)

| 用途 | MSO_SHAPE | 说明 |
|-----|-----------|------|
| 右箭头 → | `RIGHT_ARROW` | 流程下一步 |
| 上箭头 ↑ | `UP_ARROW` | 增长 |
| 下箭头 ↓ | `DOWN_ARROW` | 下降 |
| 双向箭头 ↔ | `LEFT_RIGHT_ARROW` | 对比 / 关联 |
| 折线右箭头 | `BENT_ARROW` / `CURVED_RIGHT_ARROW` | 转折 |
| 五边形流程 | `PENTAGON` | 流程节点(横排) |
| V 形 | `CHEVRON` | 流程节点(空间紧) |

### 几何/装饰

| 用途 | MSO_SHAPE | 说明 |
|-----|-----------|------|
| 圆形头像底 | `OVAL` | 头像/数字徽章 |
| 圆角矩形 | `ROUNDED_RECTANGLE` | 标签 / 按钮态 |
| 标注气泡 | `ROUNDED_RECTANGULAR_CALLOUT` | 引述 |
| 雷电 | `LIGHTNING_BOLT` | 突破 / 创新 |
| 太阳 | `SUN` | 机会 / 启示 |
| 月亮 | `MOON` | 夜晚 / 安静主题 |
| 云 | `CLOUD` | SaaS / 网络主题 |
| 禁止 | `NO_SYMBOL` | 反模式 / 禁止 |
| 笑脸 | `SMILEY_FACE` | 用户满意 |

### 引用/装饰

| 用途 | MSO_SHAPE | 说明 |
|-----|-----------|------|
| 大引号 | 字形 `"` 或 `LEFT_BRACE` | 金句页常用 |
| 横线分隔 | `RECTANGLE` 高 0.04 in | 标题下装饰线 |
| 竖线分隔 | `RECTANGLE` 宽 0.04 in | 双栏中线 |
| 三点 ⋯ | `OVAL` × 3 | 加载 / 进行中 |

## B. 标准用法

### B1. 圆点 bullet

```python
from pptx.enum.shapes import MSO_SHAPE
from pptx.util import Inches

def add_dot(slide, x, y, size=0.18, color=ACCENT):
    dot = slide.shapes.add_shape(MSO_SHAPE.OVAL,
                                  Inches(x), Inches(y),
                                  Inches(size), Inches(size))
    dot.fill.solid(); dot.fill.fore_color.rgb = color
    dot.line.fill.background()
    return dot
```

### B2. 编号徽章 (圆 + 数字)

```python
def add_badge(slide, x, y, num, diameter=0.7,
              fill=PRIMARY, fg=RGBColor(255,255,255)):
    circle = slide.shapes.add_shape(MSO_SHAPE.OVAL,
                                     Inches(x), Inches(y),
                                     Inches(diameter), Inches(diameter))
    circle.fill.solid(); circle.fill.fore_color.rgb = fill
    circle.line.fill.background()
    tf = circle.text_frame
    tf.text = str(num)
    p = tf.paragraphs[0]
    p.alignment = PP_ALIGN.CENTER
    r = p.runs[0]
    r.font.bold = True
    r.font.size = Pt(20)
    r.font.color.rgb = fg
    r.font.name = "Arial"
    return circle
```

### B3. 流程节点 (五边形)

```python
def add_pentagon(slide, x, y, w, h, text, fill=PRIMARY):
    shp = slide.shapes.add_shape(MSO_SHAPE.PENTAGON,
                                  Inches(x), Inches(y),
                                  Inches(w), Inches(h))
    shp.fill.solid(); shp.fill.fore_color.rgb = fill
    shp.line.fill.background()
    tf = shp.text_frame
    tf.text = text
    p = tf.paragraphs[0]; p.alignment = PP_ALIGN.CENTER
    r = p.runs[0]; r.font.size = Pt(14); r.font.bold = True
    r.font.color.rgb = RGBColor(255,255,255); r.font.name = "微软雅黑"
    return shp

# 用法:水平排五个节点
for i, label in enumerate(["调研","设计","开发","测试","上线"]):
    add_pentagon(slide, 0.7 + i*2.4, 3.5, 2.2, 0.8, label)
```

### B4. 强调箭头 (右箭头)

```python
def add_arrow_right(slide, x, y, w, h, fill=ACCENT):
    a = slide.shapes.add_shape(MSO_SHAPE.RIGHT_ARROW,
                                Inches(x), Inches(y),
                                Inches(w), Inches(h))
    a.fill.solid(); a.fill.fore_color.rgb = fill
    a.line.fill.background()
    return a
```

### B5. 标题装饰线

```python
def add_accent_line(slide, x, y, length=1.0, thickness=0.05, color=ACCENT):
    """标题下面那条 1 寸长的强调横线 (替代大色块的轻量做法)"""
    bar = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE,
                                  Inches(x), Inches(y),
                                  Inches(length), Inches(thickness))
    bar.fill.solid(); bar.fill.fore_color.rgb = color
    bar.line.fill.background()
    return bar
```

## C. Unicode 字形 (MSO_SHAPE 没有的图形)

某些图标 MSO_SHAPE 没有对应,用 unicode 字形渲染成 PNG 嵌入。Win/Mac 默认字体覆盖良好。

### 推荐字形 (避开 emoji,用单色符号)

```
✓ ✔ ✗ ✘   对号 / 错号
✦ ✧ ✪ ★    星
→ ← ↑ ↓ ↔   箭头
⬛ ⬜ ◆ ◇    方块菱形
● ○ ◉ ◎    圆
※ ◇ ⬢ ⬡    装饰
☰ ☱ ☲ ☳    汉字六十四卦类(简洁)
∴ ∵ ⇒ ⇔    数学
№ ¶ § †     文档符号
↗ ↘ ↙ ↖    斜箭头
⌘ ⌥ ⌃ ⏎    键盘
```

### 用 render_icon.py 生成

```bash
# 生成对号 PNG (强调色,96px)
python scripts/render_icon.py "✓" --color "#38B2AC" --size 96 -o slides/check.png

# 然后嵌入幻灯片
slide.shapes.add_picture("slides/check.png", Inches(1), Inches(2),
                          width=Inches(0.5))
```

## D. 用图标的几条原则

1. **同一 deck 风格统一** —— 全用 MSO_SHAPE 或全用字形 PNG,不要混
2. **颜色限定** —— 只用 PRIMARY / SECONDARY / ACCENT / GREY,不要每个图标独立配色
3. **大小克制** —— bullet 前的 dot 0.15-0.2 in;独立装饰图标 0.5-1.5 in;不要超过 2 in
4. **间距统一** —— 图标右侧到文字的间距固定,通常 0.2-0.3 in
5. **不替换文字** —— 图标是辅助,不是表意主体;一个 ★ 不能代替"重点"两字
6. **避免 emoji** —— emoji 在不同系统渲染差异大,且自带颜色与你的配色冲突

## E. 不要做什么

- ❌ 在每页都堆图标
- ❌ 用网上随便下载的彩色图标 (主题不统一)
- ❌ 用 emoji (🚀💡⚡) 当严肃汇报的图标
- ❌ 图标尺寸大于标题字号高度的 2 倍
- ❌ 用 STAR / HEART 装饰严肃议题 (融资额、合规)